Siril

Release 1.2.0

Free-Astro Team

Mar 05, 2024

 GENERAL

1 Installation 3
1.1 Installation on GNU/Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Installation on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Installation on macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4 Installation from source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2 Graphical User Interface 15

2.1 Main interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2 Burger Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3 Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.4 Image information window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3 Preferences 29
3.1 Preferences (GUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.2 Preferences (commands) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4 File Formats 55
4.1 Bit Depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.2 Common File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.3 FITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.4 Astro-TIFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
4.5 SER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4.6 IRIS PIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

5 Sequences 69
5.1 A set of two or more FITS files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.2 A single SER file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.3 A single FITS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.4 Loading a sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.5 Frame selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.6 Sequence export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.7 Sequence information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

6 Definitions and workflow 75

7 Preprocessing 77
7.1 Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.2 Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.3 Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
7.4 Stacking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

i
8 Processing 129
8.1 Image stretching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
8.2 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
8.3 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
8.4 Star Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
8.5 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.6 Background Extraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
8.7 Extraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.8 Linear Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
8.9 RGB compositing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
8.10 Merge CFA Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.11 Pixel Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

9 Plotting Feature 227

9.1 Registration Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
9.2 Photometry Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
9.3 Shared options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
9.4 Plot interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

10 Dynamic PSF 235

10.1 Initial star candidates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
10.2 Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
10.3 Minimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
10.4 Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
10.5 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
10.6 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

11 Astrometry 245
11.1 Platesolving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
11.2 Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

12 Photometry 261
12.1 Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
12.2 Quick photometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
12.3 Light curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

13 Image inspectors 277

13.1 Tilt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
13.2 Aberration Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

14 Statistics 281
14.1 Estimators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

15 Scripts 285
15.1 Using scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
15.2 Populating the list of scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
15.3 Built-in scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
15.4 Getting more scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
15.5 Writing your own . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

16 Headless mode 291

16.1 Command Stream (Pipe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

17 Path parsing 293

17.1 Syntax example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

ii
 17.2 Finding a file with path parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
17.3 Writing a file with path parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
17.4 Using wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

18 Livestacking 299
18.1 Livestacking (GUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
18.2 Livestacking (Headless) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

19 Commands 303

20 How to report issues 363

20.1 Check changelogs and bug trackers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
20.2 Send us useful information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
20.3 How to contact us? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

Bibliography 365

Index 367

iii
iv
 Siril, Release 1.2.0

This is the documentation of version 1.2.0.

Siril is an astronomical image processing tool, specially tailored for noise reduction and improving the signal/noise
ratio of an image from multiple captures, as required in astronomy.

Siril can align automatically or manually, stack and enhance pictures from various file formats, even image sequence
files (films and SER files).
Programming language is C, with parts in C++. Main development is done with most recent versions of shared libraries
on GNU/Linux. Contributors are welcome.
This is the documentation, it tries to describe all Siril functions. If the equivalent of a GUI function exists on the
command line, then it is given in an insert. Other useful resources can be found at our main website siril.org.
You can find here an index of Siril commands.
To report any problems in the documentation please open a ticket at the following address: https://gitlab.com/free-astro/
siril-doc.
A problem in the translation of the documentation should be reported here: https://gitlab.com/free-astro/
siril-localized-doc.

GENERAL 1
Siril, Release 1.2.0

2 GENERAL
 CHAPTER

ONE

INSTALLATION

Each version of Siril are distributed for the 3 most common platforms (Windows, MacOS, GNU / Linux) and can be
downloaded on the Siril website. But of course, as Siril is a free software and you can build the application from the
sources.

Tip: It may be useful to check the integrity of the binary or package you have just downloaded. The list of SHA
checksum is available on this page, in json format.

At the end of the installation you can try the capabilities command to learn more about your installation.

Siril command line

capabilities

Lists Siril capabilities, based on compilation options and runtime

Understanding Siril version numbers

Starting with 1.0 version, stable versions of Siril (such as 1.0, 1.2, etc.) are indicated by even numbers and are de-
signed for everyday use. Development versions, indicated by odd numbers (such as 0.99.0, 1.1.0, etc.), are not usually
available as packages or binary executables, and must be compiled by the user. The third and last number, called micro
numbering, corresponds to the number of releases that brought bug fixes and other small contributions (such as 1.0.1,
1.0.2, 1.0.3, etc.).

1.1 Installation on GNU/Linux

1.1.1 Installation on Debian

The binary package is available on Debian testing and an old version for stable. It can be installed via apt, with superuser
privileges:

3
Siril, Release 1.2.0

1.1.2 Installation on Ubuntu or Linux Mint

Official repositories

As for debian, it is available in the repositories, but the version can be outdated:

sudo apt install siril

PPA repositories

The newer version is thus available in our PPA, which is the preferred way to install Siril on Ubuntu or Linux Mint:

sudo add-apt-repository ppa:lock042/siril

sudo apt-get update
sudo apt-get install siril

1.1.3 Installation of the AppImage binary

For GNU/Linux systems, we also decided to provide bundled binaries with AppImage (x86_64) and flatpak that works
on GNU/Linux-like systems. To run the AppImage binary, you just have to download it and allow it to run using the
command:

chmod +x Path/To/Application/Siril-x.y.z-x86_64.AppImage

By replacing with the correct path and x,y and z with the version numbers. Then a simple double-click on the AppImage
starts Siril.

1.1.4 Installation of the flatpak

Another way to install sable version of siril is to use the flatpak, the utility for software deployment and package
management for Linux. To install flatpak, type the following command:

flatpak install flathub org.free_astro.siril

Then, to run the application:

flatpak run org.free_astro.siril

1.2 Installation on Microsoft Windows

1.2.1 Installation with the installer

The recommended way to install Siril is to use the provided installer which will guide you step by step.
The Siril setup wizard will install all the necessary files in the right place and at the end you will have the choice to
create or not a shortcut on the desktop.

4 Chapter 1. Installation
 Siril, Release 1.2.0

Fig. 1: First screen of the installer, you need to accept the agreement to continue.

Note: Siril will be installed in C:\Program Files\Siril. If you don't have the rights to install to this folder, use a portable
version instead (see Installation of the portable binary.)

1.2.2 Installation of the portable binary

If you want to use Siril without installing all kinds of files on your computer (for example if you don't have administrator
permissions on the machine), then it is recommended to use the portable version. It comes in the form of a zip file,
which you just have to extract to the location of your choice, then go to the bin folder to run siril.exe. You can also
create a shortcut on your desktop to make it easier to launch the application.

Warning: Be careful, under no circumstances you should move the exe file, or any other file. Otherwise Siril will
not run.

1.2. Installation on Microsoft Windows 5

Siril, Release 1.2.0

Fig. 2: Last screen of the installer. You can chose to start Siril right after installation, and to open the tutorial explaining
the first steps.

6 Chapter 1. Installation
 Siril, Release 1.2.0

1.2.3 Installation from the Microsoft Store

It is now possible to install Siril via the Microsoft Store.

1. Go to the Start button, and then from the apps list select Microsoft Store.
2. Type Siril in the search entry.
3. Open the page corresponding to Siril, and then select Get.

Note: However, it is important to note that Siril updates in the Store are usually done with a small delay due to the
upload process which is quite complex.

1.2.4 Building on Windows with Msys2

These instructions are made for compiling on Windows with MSYS2 distribution using MinGW. MSYS2 requires 64
bit Windows 7 or newer, and does not work with FAT filesystems.
Download MSYS2 64bit, a software distribution and building platform for Windows and run the installer x86_64 for
64-bit. When asked, specify the directory where MSYS2 64-bit will be installed.
Run MSYS2 directly from the installer or later MSYS2 MinGW 64-bit from Start menu or shortcut.

Warning: Make sure to launch MinGW 64-bit (check that the icon is blue at the top of the terminal window).

First, update the package database and core system packages by typing (for more info about pacman see this page):

pacman -Syu

1.2. Installation on Microsoft Windows 7

Siril, Release 1.2.0

Installing dependencies

Note: Automake is the legacy (stable) build method, now being replaced by meson (experimental) build system.

To install the dependencies, enter the following command:

pacman --noconfirm -S --needed base-devel \

mingw-w64-x86_64-toolchain \
mingw-w64-x86_64-cmake \
git \
automake \
mingw-w64-x86_64-lcms2 \
mingw-w64-x86_64-curl \
mingw-w64-x86_64-json-glib \
mingw-w64-x86_64-meson \
mingw-w64-x86_64-ninja \
mingw-w64-x86_64-fftw \
mingw-w64-x86_64-exiv2 \
mingw-w64-x86_64-gtk3 \
mingw-w64-x86_64-libconfig \
mingw-w64-x86_64-gsl \
mingw-w64-x86_64-opencv \
mingw-w64-x86_64-libheif \
mingw-w64-x86_64-ffms2 \
mingw-w64-x86_64-cfitsio \
mingw-w64-x86_64-libraw

Building from source

The source code is stored on a gitlab repository, you can download it with this command the first time:

git clone https://gitlab.com/free-astro/siril.git

cd siril
git submodule update --init

Now, generate the build system and compile the code by typing:

meson setup _build --buildtype release

ninja -C _build install

To launch your build of Siril, run MSYS2 64-bit and type siril's command name:

siril

You can also create a shortcut to siril.exe to start it, the default location is /mingw64/bin/.
To update your version, run MSYS2 64-bit then:

pacman -Syu
cd siril
git pull --recurse-submodules
(continues on next page)

8 Chapter 1. Installation
 Siril, Release 1.2.0

(continued from previous page)

meson setup _build --reconfigure
ninja -C _build && ninja -C _build install

If git pull does not show any change, there is no need to rebuild by running the make command. Otherwise, it will
update your build.
After that just launch the build by typing:

siril

1.3 Installation on macOS

1.3.1 Installation of our app

The macOS app is provided per architecture:

• Intel (macOS 10.13+)
• Apple Silicon (macOS 11+)
Choose the link corresponding to your processor architecture and download the disk image. Once downloaded, double-
click to open it.

A new window pops up. Now drag the Siril icon and drop it on the Applications one.
Congratulations, Siril is now installed.

1.3.2 Installation from Homebrew

Homebrew is similar to MacPorts and provides packages (aka formulae) to install, either by compiling them from
source or by using pre-compiled binaries (aka bottles). To install Homebrew, click here. Siril can be installed with:

brew install siril

Note: Please be aware that it was announced that Homebrew is using analytics. To turn this off, run: brew analytics
off You can read more about this on Brew Analytics.

1.3. Installation on macOS 9

Siril, Release 1.2.0

10 Chapter 1. Installation
 Siril, Release 1.2.0

1.4 Installation from source code

Installation from source code is required if you want the latest features, if the past release is getting old, if you want to
participate in improving Siril or not use all the dependencies.

1.4.1 Getting the source code

The source code is stored on a git repository, which you can download with this command the first time:

git clone --recurse-submodules https://gitlab.com/free-astro/siril.git

And update it the following times with these commands in the base siril directory:

git pull
git submodule update --recursive

1.4.2 Dependencies

Siril depends on a number of libraries, most of which should be available in your Linux distribution or package manager
of choice. The names of the packages specific to operating systems are listed in each section below. Mandatory
dependencies are:
• gtk+3 (Graphical user interface library), at least version 3.20.
• adwaita-icon-theme (icons) to support gtk's look and feel.
• cfitsio (FITS images support).
• fftw (Discrete Fourier Transform library).
• gsl (The GNU Scientific Library), version 1 or 2 starting with release 0.9.1 or SVN revision 1040.
• OpenCV and a C++ compiler for some image operations.

Note: Even if Siril can run in console since version 0.9.9, it is still linked against the graphical libraries, so you still
need GTK+ to compile and run it.

Optional dependencies are:

• openmp for multithreading. Although optional, this dependency is highly recommended as the performance will
be much better. The flag of this option is set to true by default. That means if openmp is not installed on your
machine, you must add -Dopenmp=false in the meson setup.
• libraw, libtiff, libjpeg, libpng, libheif for RAW, TIFF, JPEG, PNG and HEIF images import and export. The
libraries are detected at compilation-time.
• FFMS2 for film native support as image sequences. It also allows frames to be extracted from many kinds of
film, for other purposes than astronomy. Versions < 2.20 have an annoying bug. It is recommended to install the
latest version.
• ffmpeg (or libav), providing libavformat, libavutil (>= 55.20), libavcodec, libswscale and libswresample for mp4
sequence export.
• gnuplot for photometry graph creation (not required at compilation time).
• wcslib for world coordinate system management, annotations and the photometric color calibration.

1.4. Installation from source code 11

Siril, Release 1.2.0

• libconfig (Structured configuration files support), used to read the configuration file from versions up to 1.0, only
used to get old settings now.
• libjson-glib for update checking (useless if you build an non-released version).
• Exiv2 to manage image metadata.
• libcurl OR glib-networking with its HTTP backend for online operations like update checks, astrometry and
photometry requests.

Build dependencies

To install from source code, you will have to install the base development packages:

git, autoconf, automake, libtool, intltool, pkg-tools, make, cmake, gcc, g++

The compilers gcc and g++ from this list can be replaced by clang and clang++ (we use them for development), probably
others as well.
The autotools packages (autoconf, automake, probably some others) can be replaced by meson.

1.4.3 Generic build process

Siril can be compiled either using autotools or meson.

Meson

The recommended way is to use meson and ninja:

meson setup _build --buildtype release

cd _build
ninja
ninja install

To disable some dependencies or features, use meson options -Dfeature=false or -Denable-feature=yes de-
pending on the case.
Table below lists all configurable options.

12 Chapter 1. Installation
 Siril, Release 1.2.0

Option Type Value Choices Description

relocatable- combo platform- [ 'yes', 'no', build with resources considered bundled un-
bundle default 'platform- der the same prefix
default' ]
openmp boolean true N/A build with OpenMP support
json_glib boolean true N/A build with json glib support
exiv2 boolean true N/A build with exiv2 support
libraw boolean true N/A build with LibRaw support
libtiff boolean true N/A build with TIFF support
libjpeg boolean true N/A build with JPEG support
libpng boolean true N/A build with PNG support
libheif boolean true N/A build with HEIF support
ffms2 boolean true N/A build with FFMS2 support
ffmpeg boolean true N/A build with FFmpeg support
enable-libcurl combo platform- [ 'yes', 'no', Use libcurl instead of GIO
default 'platform-
default' ]
libconfig boolean false N/A build with libconfig support
criterion boolean false N/A build with criterion support
wcslib boolean true N/A build with WCSLIB support

Autotools

The autotools ways is well known in the unix world, once the source code has been downloaded and the prerequisites
have been installed, the general way to build it is as such:

./autogen.sh
make
make install

possibly with superuser privileges for the last line.

You may want to pass specific options to the compiler, for example like that if you want optimisation and installation
in /opt instead of the default /usr/local:

CFLAGS='-mtune=native -O3' ./autogen.sh --prefix=/opt

To launch Siril, the command name is siril or siril-cli.

1.4.4 Installation on Debian-like systems

You may want to build a .deb package instead of using a non-packaged version, in that case see this help. In particular,
to install dependencies, you can use the command:

apt build-dep siril

Otherwise, here is the list of packages for the current version:

• Packages required for the build system:

autoconf automake make gcc g++ libtool intltool pkg-config cmake

1.4. Installation from source code 13

Siril, Release 1.2.0

• List of packages for mandatory dependencies:

libfftw3-dev libgsl-dev libcfitsio-dev libgtk-3-dev libopencv-dev

libexiv2-dev

• List of packages for optional dependencies:

wcslib-dev libcurl4-gnutls-dev libpng-dev libjpeg-dev libtiff5-dev

libraw-dev gnome-icon-theme libavformat-dev libavutil-dev libavcodec-dev
libswscale-dev libswresample-dev libjson-glib-dev libheif-dev

for film input (AVI and others) support:

libffms2-dev

1.4.5 Installation on Arch Linux

Two packages are available on AUR: siril and siril-git. Download the PKGBUILD or the repository, install de-
pendencies, run makepkg to build the package and pacman -U to install it.
Dependencies (mandatory and a few optional):

pacman -S base-devel cmake git intltool gtk3 fftw cfitsio gsl opencv
exiv2 libraw wcslib

1.4.6 Build Failures

Every commit to Siril git is automatically built in a standard build environment for Linux, Windows and MacOS using
the gitlab CI infrastructure. This means that we have high confidence that the master branch, as well as tagged releases,
will build successfully given a correctly set up build environment with the necessary dependencies installed.
If you experience a build failure it is likely that this indicates a problem with your build environment or incorrectly in-
stalled dependencies - remember many distributions require separate installation of development packages that contain
the necessary header files. Check the CI report for the git commit you are trying to build. In the unlikely event that
there is a build failure shown, rest assured the team is working to fix it. Otherwise, if the CI pipeline shows green ticks,
you will need to review and fix any issues with your own build environment.
If you still believe you have found a build issue that has not been flagged by the CI pipeline - for example if you're
building on a different platform such as BSD that the developers don't regularly use - then feel free to raise an issue on
gitlab.
Note that issues should only be raised against the master branch or tagged releases. If you are testing new features in
merge requests, please provide feedback in comments against the relevant merge request.

14 Chapter 1. Installation
 CHAPTER

TWO

GRAPHICAL USER INTERFACE

The Graphical User Interface (GUI) allows you to process your images manually, as well as using scripts or typing
commands. To learn how to use Siril in headless mode, please refer to this section.
Siril's GUI is written using GTK, a free and open source cross-platform toolkit for GUI creation. Currently, the version
used is version 3.
The following subsections take you through the main interface window and useful menus.

2.1 Main interface

When launching Siril, the main interface opens.

Note: Click anywhere onto the image below to display its functions.

15
Siril, Release 1.2.0

Image area

This area displays the currently loaded image. Click on Red, Green or Blue to switch between the different layers (color
images only, a single BW tab is available for mono images).
Right-click on the image to display a contextual menu:

Tip: When no image is loaded, double-clicking on the image area pops the Open dialog.

Todo: Explain or link (when created) to the different items

Back to figure

Open

Click on these icons (from left to right) to:

• open a file
• open a recent file
• change the Home directory
Back to figure

16 Chapter 2. Graphical User Interface

 Siril, Release 1.2.0

Livestack

Click on this button to start a Livestacking session.

Back to figure

Undo/Redo

Use these buttons to undo/redo last actions. This is only available if last action has been done through GUI, not by
typing a command.
Back to figure

Image processing

Click on this button to display the Processing menu.

Back to figure

Scripts

Click on this button to display and launch the scripts.

Back to figure

Information bar

This bar displays the current version of Siril and the path to the current working directory.
• To the right, informationabout available RAM and disk space id also given.
• You can change the available number of threads used by Siril using the +/- signs.
Back to figure

Save

These buttons are used to save your results:

• save (overwrites) the current image.
• save with a different name and/or extension.
The drop-down list at the bottom right allows you to choose the type of image recorded. It automatically adds
the extension to the file name. However, by staying in the Supported Image Files mode, it is possible to add any
extension supported by Siril by hand and it will save in the correct file format.
• take a snapshot of the current view (as seen on the screen, meaning preview strecthing, if any, is applied). There
are two possible options. Either the snapshot is saved in the clipboard, or directly copied to the disk in the
working directory.
• change the bitdepth of the current image. The choice is between 16-bit and 32-bit.
Back to figure

2.1. Main interface 17

Siril, Release 1.2.0

Fig. 1: Save dialog box.

18 Chapter 2. Graphical User Interface

 Siril, Release 1.2.0

Burger menu

Opens the main menu, also called burger menu. Gives access to Preferences, platesolving and much more.
Back to figure

Tabs

Selects one of the tabs. You can also switch between the different tabs using F1 to F7 shortcuts.
More details can be found there:
• Conversion tab
• Sequence tab
• Calibration tab
• Registration tab
• Plot tab
• Stacking tab
Back to figure

Tab window

Displays the specifics of the currently selected tab.

Back to figure

Command line

Type in a command and press Enter.

• You can press the button at the end of the line to get some help on the usage.
• You can also abort the process being currently executed by clicking on the Stop button.
Back to figure

Expand

Click on this bar to expand/retract the whole tab/tab window area.

Back to figure

2.1. Main interface 19

Siril, Release 1.2.0

Image sliders

Use the top and bottom sliders to adjust the white and black points of the previewed image (in Linear mode).

Tip: Click on the name of the Image or Sequence loaded to copy its name to the clipboard (useful to paste in a
command).

Back to figure

Preview mode

Select the preview mode for the loaded image, between the following choices:
• Linear
• Logarithm
• Square root
• Squared
• Asinh
• Autostrecth (tick the High Definition box to use a deeper 20-bit LUT instead of the default 16-bit one)
• Histogram
In Autostretch mode with color images, the toggle to the right activates/deactivates channel linking. When unlinked,
the 3 layers are stretched independantly so as to give a more balanced image.

Warning: This is just a preview of the image, not the actual data (except if Linear mode is selected). Do not forget
to stretch your images before saving them.

Back to figure

Special views

Use these toggles to show previewed images:

• in inverted colors
• in false colors
Back to figure

Astrometry tools

Use these toggles to show:

• astrometric annotations
• celestial grid

Warning: The loaded image needs to be plate-solved for these buttons to be active.

20 Chapter 2. Graphical User Interface

 Siril, Release 1.2.0

Back to figure

Quick photometry

Use this toggle to trigger the quick photometry mode.

Back to figure

Zoom

Use these buttons to:

• Zoom out
• Zoom in
• Zoom to fit the avaialble window space
• Zoom to actual size

Tip: Ctrl+left clic will allow to navigate into the picture

Tip: Ctrl+mouse scroll will zoom in/out and Ctrl + 0 / 1 will zoom to fit/100%.

Back to figure

Geometric transformations

Use these buttons to:

• Rotate left
• Rotate right
• Mirror about horizontal axis
• Mirror about vertical axis
Back to figure

Frame selection

Click on this button to open the frame selector.

Back to figure

2.1. Main interface 21

Siril, Release 1.2.0

2.2 Burger Menu

2.2.1 First page

Image Information

Accesses the other page of this menu.

Preferences

Opens the Preferences menu.

Siril Manual

Opens the online documentation.

Check for updates

Checks if a newer version is available.

Get scripts

Opens the page to download more scripts than the ones which are shipped with Siril.

Keyboards shortcuts

Opens a panel reminding all the available Shortcuts.

About Siril

Opens a dialog showing te version information and Credits.

22 Chapter 2. Graphical User Interface

 Siril, Release 1.2.0

2.2.2 Second page

Image Plate-Solver

Opens the PlateSolving dialog.

Statistics

Opens the Statistics dialog.

Noise Estimation

Launches a noise estimation on the loaded image. Results will be writtent in the Console.

Aberration Inspector

Opens the Aberration Inspector dialog.

Information

Opens the Information dialog.

FITS Header

Displays the contents of the loaded image FITS Header.

2.2. Burger Menu 23

Siril, Release 1.2.0

Dynamic PSF

Opens the Dynamic PSF dialog.

2.3 Shortcuts

Siril uses several shortcuts to access processing tools or to manipulate the application and/or the images. These short-
cuts are all detailed in the Keyboard Shortcuts dialog accessible via the burger menu .

24 Chapter 2. Graphical User Interface

 Siril, Release 1.2.0

2.3. Shortcuts 25
Siril, Release 1.2.0

2.4 Image information window

26 Chapter 2. Graphical User Interface

 Siril, Release 1.2.0

This window provides information about what is known about the sampling of the opened image. The sampling,
sometimes also called resolution or scale, indicates how much angle of the sky is seen in one pixel, as seen through the
instrument. It depends on two things: the focal length of the instrument and the pixel size of the sensor, itself depending
on the binning mode.
FITS headers can contain this information if it was given to the acquisition software. In that case this is the values that
are shown in this window. If not available in the image metadata, because it was unknown to the acquisition software,
or more simply because the file format does not support it, this dialog will still be available and populated with default
values. They can be modified and used for various operations of Siril that require sampling information, for example
displaying FWHM in arc seconds instead of pixels.
Default values are no binning (1x1), and a focal length and a pixel size stored in the settings. The values stored in the
settings can be set from this dialog by activating the Save as default values button before clicking on Close. They can
also be set by performing an astrometric resolution on the image, also called plate solving, if the option to update the
default values when a result is found is enabled in the preferences.
The values displayed in this window will be stored in the current loaded image and if this image is saved as FITS, they
will be stored in the FITS header.
Binning management can take two forms depending on the acquisition software: the real pixel size is given but has
to be multiplied by the binning (when Real pixel size is checked), the already multiplied pixel size is given (when
unchecked).

2.4. Image information window 27

Siril, Release 1.2.0

28 Chapter 2. Graphical User Interface

 CHAPTER

THREE

PREFERENCES

Preferences are settings which are persistent for every session of Siril, and which define your prefered choices for many
of the tools.
Since version 1.2.0, they are accessible both from the user interface or programatically, by using set/get commands.
By default, the preference file is located at:
• ~/.config/siril/config.ini (Linux)
• %LOCALAPPADATA%sirilconfig.ini (Windows)
• ~/Library/Application Support/org.free-astro.Siril/siril/config.ini (MacOS)
If you wish to have multiple configuration files, you can choose which one to start from by opening a terminal and
typing:

siril -i path/to/my_other_config.ini

Warning: Siril needs to be in your path to use siril as in the line above. Otherwise, use the full path to Siril
binary.

3.1 Preferences (GUI)

Preferences are accessible from the Burger menu or with the shortcut Ctrl + P. There are 10 pages and each page
representing a theme. The preferences allow more or less advanced users to optimize Siril to best suit their needs. Some
settings can have a negative impact on Siril's performance, so it is advisable to change the settings only when you know
what you are doing. There are three buttons at the bottom of the preferences dialog box. Reset restores all settings to
the default value, Cancel cancels the current changes and Apply will close the dialog box and save the settings.

3.1.1 FITS/SER debayer

The FITS/SER debayer tab allows the user to define the debayer settings for FITS, SER or TIFF files. Consequently,
this tab is only usable for a user with an OSC camera. It is advisable to leave the default settings as Siril will auto-
matically define the correct settings to use. However, in the case of a TIFF file that is not an AstroTIFF, or a file that
does not have all the required keywords, it may be necessary to adjust the settings manually. In this case, you have to
uncheck the button Bayer information from file's header if available. This action will unlock several settings that the
user can change.
• Bayer/mosaic pattern: This drop-down menu allows you to choose the type of Bayer matrix used by the camera.
It is generally indicated in the manufacturer's information. Be careful though, this field is closely linked to the

29
Siril, Release 1.2.0

Fig. 1: Page 1 of preferences dialog

30 Chapter 3. Preferences
 Siril, Release 1.2.0

option Debayer FITS files in top-down if no explicit keywords found and the results will be different whether it
is checked or not. More explanation on this last option can be found here.
• X offset: In rare cases, files are recorded with a Bayer array shift. We can define an offset of 1 on the X axis,
and an offset of 1 on the Y axis. Here the value defines if there is an offset in X.
• Y offset: Y offset of Bayer array.
Changing these settings will involve a different demosaicing each time. That's why it is strongly advised to leave the
settings in their default state, unless you are really sure of what you are doing.
Another option that has less impact on the final result is the choice of the demosaicing algorithm proposed in Debayer
interpolation. The choices are the following:
• Fast Debayer is the fastest algorithm available in Siril. However, other algorithms listed below are often quite
better.
• VNG4, Threshold-Based Variable Number of Gradients, works on a 5x5 pixel neighborhood around each source
pixel. It is a very good algorithm for flat areas of the image (like sky background) but produces artifacts in high
contrast areas (like stars).
• AHD, Adaptive Homogeneity-Directed, is another well known debayer algorithm. However it usually shows
artefacts in the background and bad star shapes.
• AMaZE, Aliasing Minimization and Zipper Elimination, is an algorithm that gives good results specially on low
noise captures.
• DCB, Double Corrected Bilinear, a more recent algorithm, can show some artifacts in the background like AHD.
• HPHD, Heterogeneity-Projection Hard-Decision, is an old algorithm giving some nice results but that is quite
slow.
• IGV and LMMSE are very good when working with very noisy images. However, IGV tends to lose some
chromatic information, while LMMSE is one of the most computational expensive demosaicers and needs a lot
of memory.
• RCD, Ratio Corrected Demosaicing, intends to smooth the colour correction errors that are common in many
other interpolation methods. It does an excellent job for round edges, for example stars, and is therefore the
default algorithm used in Siril.
For the X-Trans sensor, a special algorithm called Markesteijn is used regardless of the method selected in the pref-
erences. For the latter, it is possible to define the requested quality with the X-Trans demosaicing quality option. It
defines the number of passes for the X-Trans Markesteijn demosaicing algorithm, 1 is the default, 3 may be slightly
better but slower.

Warning: For on-the-fly demosaicing of SER files, the RCD algorithm is always used regardless of the choice
made in the drop-down menu. This allows Siril to be more efficient in terms of execution speed and to offer a good
quality.

3.1. Preferences (GUI) 31

Siril, Release 1.2.0

3.1.2 FITS Options

Fig. 2: Page 2 of preferences dialog

The FITS Options page groups all the settings related to the native format used by Siril.
• FITS extension: By default, the value is set to .fit However, many capture programs use the .fits extension.
In this case we advise you to update the value. All files created by Siril will have the extension defined here.
Moreover, only sequences with the extension defined in the preferences can be loaded. It is therefore not possible
to open a .fits sequence and a .fit sequence without updating this value. Supported extensions are:
– .fit
– .fits
– .fts
All of them can be appended by the .fz extension if the files are compressed.

Siril command line

setext extension

32 Chapter 3. Preferences
 Siril, Release 1.2.0

Sets the extension used and recognized by sequences.

The argument extension can be "fit", "fts" or "fits"

• Default Type: By default, Siril works in 32-bit floats in the range [0, 1]. This is the best way to keep a high
precision. However, for hard disk space considerations a user may decide to work in 16-bit unsigned (in the range
[0, 65535]). Be careful though, a 16-bit stacking can lose a lot of information.
• Allow FITS cubes to have images of different sizes: This can be useful to open scientific FITS files that were
not created by Siril and that contain multiple images of different dimensions, which would otherwise considered
as invalid Siril FITSEQ files. The JWST images are a good example of the use of this option.
• Enable Aladin compatibility (CTYPE3 = 'RGB '): Aladin considers a 3D FITS cube as a RGB image (Red,
Blue and Green components) if the FITS keyword CTYPE3 = 'RGB ' is specified in the header. In this case any
BITPIX value are supported. Without the FITS keyword CTYPE3 = 'RGB ' set, only FITS cube with 3 frames
sharing the same dimension and with a BITPIX=8 will be automatically detected as RGB FITS.

Warning: This option may conflict with the astrometry feature and should only be activated if it is really necessary.

• Update pixel size of binned images: Used for image sampling computation, pixel size can be given in two
different ways: the real pixel size is given but has to be multiplied by the binning (when checked), the already
multiplied pixel size is given (when unchecked). It depends on the acquistion software used to create the FITS.
• FITS compression: La compression peut être intéressante dans certains cas où l'espace sur le disque dur est un
point clé du traitement. You can find more information in the section dedicated to the FITS format, here.
The compression adds the extension .fz to the files created. Siril is able to open a sequence with the fz extension
without having to change any value in the preferences.

Siril command line

setcompress 0/1 [-type=] [q]

Defines if images are compressed or not.

0 means no compression while 1 enables compression.

If compression is enabled, the type must be explicitly written in the option -type= ("rice", "gzip1", "gzip2").
Associated to the compression, the quantization value must be within [0, 256] range.

For example, "setcompress 1 -type=rice 16" sets the rice compression with a quantization of 16

3.1. Preferences (GUI) 33

Siril, Release 1.2.0

3.1.3 Astrometry

Fig. 3: Page 3 of preferences dialog

This tab contains all the options related to astrometry. Astrometry is a feature strongly implemented in Siril. When the
image is solved (i.e. when the astrometry has been successful), it is possible to display the names of the known objects.
In particular those listed in the large astronomical catalogs. The annotation part allows to define which catalogs can be
used for the display of object names. Currently there are 6 of them, and they can be deselected to be ignored:
• Messier catalog
• New General Catalogue
• Index Catalogue
• Lynds' Catalogue of Bright Nebulae
• Sharpless Catalogue
• Catalogue of Brightest stars
In addition to this list, there are two more catalogs that are filled in by the user. One concerning the deep sky objects,
the other concerning the solar system. They can be better described in the annotation annotations section of this
documentation.

34 Chapter 3. Preferences
 Siril, Release 1.2.0

By clicking on the button Show object names (only if the image has been plate-solved), the annotations are

displayed on the image. It is also possible to click on the button that displays the celestial grid . The latter, by
default, adds a compass to the center of the image. The Compass section allows you to define the desired location for
the display of the compass.
The World Coordinate System section allows you to choose
• Formalism 1: In the PC i_j formalism, the matrix elements 𝑚𝑖𝑗 (linear transformation matrix) are encoded in
PC i_j (floating-valued) header cards, and si as CDELT i. The i and j indices are used without leading zeroes,
e.g. PC 1_1 and CDELT 1. The default values for PC i_j are 1.0 for 𝑖 = 𝑗 and 0.0 otherwise. The PC i_j
matrix must not be singular; it must have an inverse. Furthermore, all CDELT i must be non-zero.
• Formalism 2: The CD i_j (floating-valued) keywords encode the product 𝑠𝑖 𝑚𝑖𝑗 . The i and j indices are used
without leading zeroes, e.g. CD 1_1. The CD i_j matrix must not be singular; it must have an inverse. CDELT
i and CROTA i are allowed to coexist with CD i_j as an aid to old FITS interpreters, but are to be ignored by
new readers.
The Local star catalogues part of the dialog window concerns the use of local catalogs to platesolve images. This
feature is described in details in the annotation section of this documentation.
An option in the General Platesolving section determines if the computed focal length and input pixel size are stored
in the settings as default values for images that don't have the corresponding metadata, when an astrometric solution is
found.

Fig. 4: Bottom of page 3 of preferences dialog (astrometry.net)

The last section is dedicated to the solve-field plate solver from the astrometry.net suite.
• Degrees of the polynomial correction: astrometry.net can use a polynomial correction (SIP) to work with
optical aberrations, this is the order of the polynomial model. 0 disables it.

3.1. Preferences (GUI) 35

Siril, Release 1.2.0

• Sampling tolerance: percent below and above the expected sampling to allow. Given sampling is multiplied or
divided by 1 + this / 100.
• Target radius: allowed search radius around the target coordinates for the solve (degrees). Unused for blind (no
target passed) solves.
• Do not delete .xyls: the list of stars is passed to solve-field as a FITS table, check this to keep the file in the
working directory.
• Do not delete .wcs: the results from solve-field are stored in a FITS header with a file name ending in .wcs.
Check this to not remove this file.
• Maximum seconds to try solving: allowed time for the solve for each catalog file. It can be used as the total
solve time only if solve-field is configured to do so in its configuration file.
• Location of local astrometry.net solver: In order to use Astrometry.net locally in Siril, it can be necessary
to tell to Siril the path where it is located. On UNIX-based systems, it is generally in the PATH variable and
not necessary. For Windows, if you did not modify the default installation directory, that is %LOCALAPP-
DATA%\cygwin_ansvr, Siril will search for it without additional setup. If you have cygwin and have build as-
trometry.net from the sources, you must specify the location of cygwin root here.
• Show solve-field output: print the output of the solver in Siril's main log window, otherwise, only the outcome
will be given.

3.1.4 Pre-processing

The pre-processing tab contains all the elements related to the steps that are executed until the stacking. Here it is
possible to manage a library of an offset, a dark and a flat, the output name of the stacked file or specific corrections
for cameras that use the X-Trans sensor.
• Dark/Bias/Flat Libraries: In this section it is possible to load an offset, a dark and a flat that will be used by
default in the pre-processing if the button to the right of the text box, Use it as default is checked. Each path will
also be stored in the reserved keywords $defbias, $defdark and $defflat (one token $) which can be used
when saving a stacking result. As far as bias is concerned, it is possible to use more than just a file path. Indeed,
in the Siril team we encourage users to use synthetic bias as explained in this tutorial. Several values are then
possible as long as the first character entered is the = sign. It is possible to use a fixed integer value like =500 or
a multiplication involving the keyword $OFFSET (one token $) as long as the latter is actually registered in the
FITS file header, like 10*$OFFSET. More details are given in the tutorial.
• Stacking default: Here we define the default name that we want to give to the stacking results. It is pos-
sible to use any value given in the FITS header as a keyword and surround it with $ tokens. If the key-
word does not exist the variable will be used, otherwise it is its value. Another reserved keyword that can
be used is $seqname$. It contains the name of the loaded sequence. For example, the following default name,
$seqname$stacked_$LIVETIME:%d$s with a sequence name r_pp_light_ and the following header:

...
DATE = '2022-12-08T22:21:14' / UTC date that FITS file was created
DATE-OBS= '2015-08-21T22:18:25' / YYYY-MM-DDThh:mm:ss observation start, UT
STACKCNT= 13 / Stack frames
EXPTIME = 300. / Exposure time [s]
LIVETIME= 3900. / Exposure time after deadtime correction
EXPSTART= 2457256.42945602 / Exposure start time (standard Julian date)
EXPEND = 2457256.51666667 / Exposure end time (standard Julian date)
...

will output r_pp_light_stacked_3900s.fit.

36 Chapter 3. Preferences
 Siril, Release 1.2.0

Fig. 5: Page 4 of preferences dialog

3.1. Preferences (GUI) 37

Siril, Release 1.2.0

• Fix Xtrans files: This setting field is very specific and only concerns possessors of certain X-Trans sensors.
Indeed, some images from these cameras show a large square in the center of the darks and bias images due to
the position of the autofocus (AF). Siril has an algorithm to eliminate it for the following cameras:
– Fujifilm X-T1
– Fujifilm X-T2
– Fujifilm X-T20
– Fujifilm X-Pro2
– Fujifilm X-E3
– Fujifilm X-H1

Fig. 6: X-Trans artifact fixed by the algorithm of Siril

In the unlikely event that your camera contains this artifact and is not supported, then it is possible to define the
correction to be applied here. The best thing to do is to contact the dev team in order to have the values to enter that
would correspond to your camera.

3.1.5 Photometry

Photometry, which is the study of light, is another feature very present in Siril. This section of the preferences allows
you to define the settings associated with this tool.
The basic principle of aperture photometry is to sum-up the observed flux in a given radius from the center of an object,
then subtract the total contribution of the sky background in the same region (calculated in the ring between the inner
and outer radius), leaving only the flux of the object to calculate an instrumental magnitude. This is described in more
detail in the Photometry section of this documentation.
• It is then possible to modify the inner radius and the outer radius to define a size that optimizes the calculated
sky value, trying to avoid the stars inside the ring. Outer must always be greater than inner. By default, the flux
aperture radius is set as twice the PSF's FWHM, however it is possible to disable this feature and define a fixed
value manually.
• Pixel range value allows users to set a limit for which the pixel is considered bad for photometry. Indeed, doing
photometry on saturated data will never give good results, but even getting close to high values may not be
suitable because it may be in the non-linear regime of sensors. A default value of 50000 ADU is set to avoid
this region, but it may vary from sensor to sensor. Negative values are also allowed because noise can average
around a positive value but still provide a few pixels with negative values.

38 Chapter 3. Preferences
 Siril, Release 1.2.0

Fig. 7: Page 5 of preferences dialog

3.1. Preferences (GUI) 39

Siril, Release 1.2.0

Fig. 8: Circle of the aperture photometry

40 Chapter 3. Preferences
 Siril, Release 1.2.0

• Finally, if known, it is highly recommended to put the value of the A/D converter gain in electrons per ADU: it
is used in the uncertainties computations, if not already provided in the headers of the processed images.

3.1.6 Analysis Tools

Fig. 9: Page 6 of preferences dialog

So far, only one image analysis tool requires adjustment parameters. It is the aberration inspector tool. In this tab you
can adjust:
• The panel size, in pixels, which defines the size of the image that will be placed in a panel. The larger the value,
the larger the size of the image in a panel. A value that is too high may prevent from seeing the defects of the
stars.
• The window size, also in pixels, which defines the size of the dialog. It is usually a good idea to increase this
value when using a 4K screen.

3.1. Preferences (GUI) 41

Siril, Release 1.2.0

Fig. 10: Aberration inspector window

42 Chapter 3. Preferences
 Siril, Release 1.2.0

3.1.7 User Interface

Fig. 11: Page 7 of preferences dialog

In this tab are listed all the adjustments related to the user interface. These are not settings that have an impact on the
processes, but on the feel and look and needs of the user.
• By default, the language of Siril is defined according to the system language. However it is possible to change
the language and define it to your needs, as long as it exists. However, keep in mind that Siril is developed in
English.
• Two themes are available:
– The dark theme (default theme)
– The light theme
Changing the theme requires a restart of the application to be fully operational.
• It is possible to adjust the font scale for users with a 4K Ultra-HD screen, or to use symbolic icons for some
icons. Theses settings also require a restart of the application.
• By default Siril remembers the size and the position of the application window each time you close it. By
checking on the Remember window size and position button you can disable this behavior.

3.1. Preferences (GUI) 43

Siril, Release 1.2.0

• The thumbnails of the images are usually visible in the open dialog boxes. The preferences allow you to not
display them if the computer has limited performance and the user does not see the need. You can also change
the size of the thumbnail display with the drop-down list.
• Default screen transfer function is the setting that allows images to be displayed according to the user's prefer-
ence. By default, this is set to linear. As this really represents what the image is, it is recommended that beginners
leave this setting at default. It is easy to forget that you are in auto-adjusted viewing and not understand why the
saved images are not as they appear on the screen. However you can always adjust the visualization in the main
window.
• Default display mode: According to the same principle, the histograms can be displayed in two modes. Either
the linear or the logarithmic mode. The latter can be very useful with the Generalized Hyperbolic Stretch tool.
You can however change the mode in each window with a histogram. In the preferences, this is a matter of setting
the default behavior.
• You can configure some texts and drawings colors to be displayed on the image in the Colors section. To do so,
simply click on the color button and choose the color of your choice. This choice concerns 5 items:
– Background extraction samples
– Standard annotations

3.1.8 Scripts

• The Scripts tab essentially contains the locations where Siril should look for scripts. Indeed, by default and
depending on the OS used, the scripts are installed in a specific place:
– /usr/local/share/siril/scripts or /usr/share/siril/scripts on GNU/Linux.
– C:\Program Files\Siril\scripts on Windows.
– /Applications/Siril.app/Contents/Resources/share/siril/scripts on MacOS, if the appli-
cation has been installed in the Applications folder.

Warning: On macOS, as the application is signed and notarized, it is impossible to modify the scripts inside
the bundle. Otherwise, the application will not start. So you have to define another path pointing to a folder
where you have write permissions.

• The Script Storage Directories field allows you to define custom folder paths to place scripts that you have
created and/or modified. Clicking on the button just below will rescan the folders and update the list of scripts
in the dedicated menu.
• The Warning Dialogs section proposes to disable:
1. The warning text that is displayed before a script is executed.
2. The check of the keyword requires which must be at the very beginning of the script in order to check if
the script is compatible with the version of Siril. We recommend to not uncheck this option.

44 Chapter 3. Preferences
 Siril, Release 1.2.0

Fig. 12: Page 8 of preferences dialog

3.1. Preferences (GUI) 45

Siril, Release 1.2.0

3.1.9 Performances

Fig. 13: Page 9 of preferences dialog

Astronomical image processing software, such as Siril, uses a lot of resources and usually requires quite powerful
computers. It is not impossible, when the computer is very busy, that it freezes completely. It is not at all recommended
to do anything else on the computer during the processing, especially Internet browsing, because browsers are very
greedy for RAM. However, it is possible to manage the maximum percentage of RAM that Siril can use.
• Ratio of available: Siril will limit itself to a ratio of the amount of free physical memory and will decrease the
size of work tasks if needed. A value above 1 means that some memory paged on a configured storage will be used
and that the overall process will be slower and the system will likely be unresponsive during some operations. If
you don't have paged memory configured on some storage, a value of 1 or above will likely result in a crash of
siril or of the operating system.
• Fixed amount (GB): Siril will limit itself to a fixed amount of memory and will decrease the size of work tasks
if needed. Configuring a memory amount larger than what is available on your system may result in a crash of
siril or of the operating system.
• The Default bit depth for HD AutoStretch option sets default bit depth for the HD AutoStretch display mode.
Higher bit depths require exponentially more memory for the LUT and take longer to recalculate it, but do a
much better job of smoothing quantization artefacts in displaying images with very narrow histogram peaks.

46 Chapter 3. Preferences
 Siril, Release 1.2.0

The default bit depth will apply from the next viewer mode change, and can be applied now using the button to
the right. Click on the Apply bit depth button to set the selected HD AutoStretch bit depth now.
• Multithreaded FFTW: this toggle button sets FFTW to use multiple threads. This can be faster (though perfor-
mance does not increase linearly with the number of processors, due to synchronization overhead), but FFTW's
planning stage takes longer for multi-threaded systems so particularly the first FFT for a given image size may
be considerably slower using multiple threads.
• FFTW planning strategy: this combobox sets the FFTW planning strategy. FFTW has multiple algorithms for
calculating a FFT and will plan a given FFT to optimize speed. It saves the results of these plans for later reuse in
a cache file called "Wisdom", so some extra time spent up-front planning can reap rewards if you calculate a lot of
FFTs of the same size. Note that wisdom is specific to a given machine: it should not be shared between machines
and should be deleted and regenerated from scratch following a memory or processor upgrade or a major change
of software environment (major OS changes, Siril major version changes). In order of speed, Estimate is fastest:
this strategy does not actually do any measurement but does planning based on a set of heuristics. Measure is
next fastest: this method actually compares the speed of different internal FFTW methods of calculating the FFT
and picks the fastest. As a result, the planning step takes longer. Patient considers even more possible plans,
and Exhaustive considers even more. If you always process images of a specific size then the more expensive
planning strategies may be worthwhile becaues of Wisdom, but if you work with images of lots of different sizes
then a cheaper planning algorithm may be more suitable.
• FFTW planning time limit: this time limit halts FFTW planning after the specified time limit. This will override
the planning strategy. Note that the time limit is not strictly enforced: FFTW will finish any non-interruptible
calculation it is performing at the time the limit is reached, and if set to zero FFTW will always as a minimum
carry out Estimate planning.

3.1.10 Miscellaneous

The last tab contains everything that does not fit in the other themes.
• Using the Undo/Redo buttons requires disk space. Lots of space in some cases. The folder containing the swap
files (which are the files necessary for the proper functioning of the undo/redo pair) can be defined in the Swap
Storage Directory section. The disk space is listed to the right of the file chooser. We advise to not change the
default settings unless you have a good reason to do so. As the choice of a good folder is critical, it is possible
to return to the default folder by clicking on Restore to Default.
• The Warnings Dialogs allows to disable some warning popups that are here to help beginners.
• Introduction Tips: At the very first start of Siril, it is possible to see a little animation showing what's new in
the application. This animation can be replayed by clicking on Play introduction.
• StarNet Executable Location: In order to use StarNet in Siril, it is necessary to tell to Siril the path where the
StarNet executable is located. For old StarNet++ v1 installations that use separate executables to process mono
and RGB files, either can be chosen - Siril will autodetect the other one if both are installed. Note that for these
old installations, the original executable names rgb_starnet++ and mono_starnet++ MUST be kept. For all
newer single-executable versions of StarNet, Siril will determine the version heuristically and interface with it
accordingly.
• StarNet Weights Location: New Torch-based versions of StarNet provide the option to provide the location of
a neural network weights file: it need not be in the same directory as the executable. This preference can be used
to set the location of a weights file to pass to StarNet, and it can be reset using the associated button. Note: this
option only works with Torch-based StarNet installations. With older StarNet installations the weights file must
be in the same directory as the executable.

Warning: This is the location of the command line version of StarNet that need to be given, not the GUI one.

3.1. Preferences (GUI) 47

Siril, Release 1.2.0

Fig. 14: Page 10 of preferences dialog

48 Chapter 3. Preferences
 Siril, Release 1.2.0

• Gnuplot Installation Directory: In order to use lightcurve feature of Siril, it is necessary to install gnuplot.
Then, you need to tell to Siril the path where gnuplot is located. On Unix-like systems, if the installation directory
is in the PATH environment variable, it is not necessary.

Warning: On macOS, it can be difficult to find the directory path because Apple does not make browsing easy
for some folders. A trick is to type Shift + Cmd + g on the open File Chooser Dialog, then directly enter the
installation path, which is usually the one set by Homebrew. Usually it is /usr/local/bin on intel computers and
/opt/homebrew/bin/ on Apple Silicon versions.

• Copyright TIFF: When saving TIFF files it is possible to customize the copyright of the dedicated EXIF meta-
data.
• Update: By default Siril checks updates at startup. You are free to disable this behavior if you don't want the
application queries our website.

3.2 Preferences (commands)

Starting from v1.2, most preferences can also be set through commands, meaning either from direct input in the com-
mand line, through scripting or in headless mode.
To get a list of all the available variables, through siril command line:

get -A

This will print a list of all the variables to the Console, with their current value and a short description (use lowercase
option -a to omit description).
The table below lists them:

Variable Default Type Comment

([Range])
core.wd (not set) direc- current working directory
tory
core.extension .fit string FITS file extension
core.force_16bit false boolean don't use 32 bits for pixel depth
core.allow_heterogeneous_fitseq false boolean allow FITS cubes to have different sizes
core.mem_mode 0 [0, 1] integer memory mode (0 ratio, 1 amount)
core.mem_ratio 0.9 [0.05, 4] double memory ratio of available
core.mem_amount 10 [0.1, double amount of memory in GB
1e+06]
core.hd_bitdepth 20 [17, 24] integer HD AutoStretch bit depth
core.script_check_requires true boolean need requires cmd in script
core.pipe_check_requires false boolean need requires cmd in pipe
core.check_updates true boolean check update at start-up
core.lang (not set) string active siril language
core.swap_dir os dependant direc- swap directory
tory
core.wcs_formalism 1 [0, 1] integer WCS formalism used in FITS header
core.catalogue_namedstars (*) string Path of the namedstars.dat catalogue
core.catalogue_unnamedstars (*) string Path of the unnamedstars.dat catalogue
core.catalogue_tycho2 (*) string Path of the deepstars.dat catalogue
continues on next page

3.2. Preferences (commands) 49

Siril, Release 1.2.0

Table 1 – continued from previous page

Variable Default Type Comment
([Range])
core.catalogue_nomad (*) string Path of the USNO-NOMAD-1e8.dat catalogue
core.rgb_aladin false boolean add CTYPE3='RGB' in the FITS header
core.copyright (not set) string user copyright to put in file header
core.starnet_exe (not set) string location of the StarNet executable
core.starnet_weights (not set) string location of the StarNet-torch weights file
core.gnuplot_dir (not set) string directory of the gnuplot installation
core.asnet_dir (not set) string directory of the asnet_ansvr installation
core.fftw_timelimit 60 double FFTW planning timelimit
core.fftw_conv_fft_cutoff 15 integer Convolution minimum kernel size to use FFTW
core.fftw_strategy 1 integer FFTW planning strategy
core.fftw_multithreaded true boolean multithreaded FFTW
starfinder.focal_length 0 [0, 999999] double focal length in mm for radius adjustment
starfinder.pixel_size 0 [0, 99] double pixel size in µm for radius adjustment
debayer.use_bayer_header true boolean use pattern from the file header
debayer.pattern 0 [0, 7] integer index of the Bayer pattern
debayer.interpolation 8 [0, 10] integer type of interpolation
debayer.top_down true boolean force debayer top-down
debayer.offset_x 0 [0, 1] integer Bayer matrix offset X
debayer.offset_y 0 [0, 1] integer Bayer matrix offset Y
debayer.xtrans_passes 1 [1, 4] integer Number of passes for the X-Trans Markesteijn al-
gorithm
photometry.gain 2.3 [0, 10] double electrons per ADU for noise estimation
photometry.inner 20 [2, 100] double inner radius for background annulus
photometry.outer 30 [3, 200] double outer radius for background annulus
photometry.inner_factor 4.2 [2, 50] double factor for inner radius automatic computation
photometry.outer_factor 6.3 [2, 50] double factor for outer radius automatic computation
photometry.force_radius true boolean force flux aperture value
photometry.aperture 10 [1, 100] double forced aperture for flux computation
photometry.minval -1500 [- double minimum valid pixel value for photometry
65536, 65534]
photometry.maxval 60000 [1, double maximum valid pixel value for photometry
65535]
astrome- 20 [0, 10000] integer percent below and above the expected sampling to
try.asnet_percent_scale_range allow
astrometry.asnet_sip_order 0 [0, 6] integer degrees of the polynomial correction
astrometry.asnet_radius 10 [0.01, 180] double radius around the target coordinates (degrees)
astrometry.asnet_keep_xyls false boolean do not delete .xyls FITS tables
astrometry.asnet_keep_wcs false boolean do not delete .wcs result files
astrome- 10 [0, 100000] integer maximum seconds to try solving
try.asnet_max_seconds_run
astrometry.asnet_show_output false boolean show solve-field output in main log
astrometry.update_default_scale true boolean update default focal length and pixel size from the
result
analysis.panel 256 [127, integer panel size of aberration inspector
1024]
analysis.window 381 [300, integer window size of aberration inspector
1600]
compression.enabled false boolean FITS compression enabled
compression.method 0 [0, 3] integer FITS compression method
continues on next page

50 Chapter 3. Preferences
 Siril, Release 1.2.0

Table 1 – continued from previous page

Variable Default Type Comment
([Range])
compression.quantization 16 [8, 256] double quantization factor for 32-bit float
compression.hcompress_scale 4 [0, 256] double Hcompress scale factor
gui_prepro.cfa false boolean type of sensor for cosmetic correction
gui_prepro.equalize_cfa true boolean equalize flat channels
gui_prepro.fix_xtrans false boolean enable correction for X-Trans sensor
gui_prepro.xtrans_af_x 0 integer if no X-Trans model found, use this
gui_prepro.xtrans_af_y 0 integer if no X-Trans model found, use this
gui_prepro.xtrans_af_w 0 integer if no X-Trans model found, use this
gui_prepro.xtrans_af_h 0 integer if no X-Trans model found, use this
gui_prepro.xtrans_sample_x 0 integer if no X-Trans model found, use this
gui_prepro.xtrans_sample_y 0 integer if no X-Trans model found, use this
gui_prepro.xtrans_sample_w 0 integer if no X-Trans model found, use this
gui_prepro.xtrans_sample_h 0 integer if no X-Trans model found, use this
gui_prepro.bias_lib (not set) string default master bias
gui_prepro.use_bias_lib false boolean use default master bias
gui_prepro.dark_lib (not set) string default master dark
gui_prepro.use_dark_lib false boolean use default master dark
gui_prepro.flat_lib (not set) string default master flat
gui_prepro.use_flat_lib false boolean use default master flat
gui_prepro.stack_default $seq- string default stack name
name$stacked
gui_prepro.use_stack_default true boolean use preferred stack name
gui_registration.method 0 [0, 7] integer index of the selected registration method
gui_registration.interpolation 4 [0, 5] integer index of the selected interpolation method
gui_registration.clamping true boolean use clamping method with Lanczos and Cubic in-
terpolation
gui_stack.method 0 [0, 4] integer index of the selected method
gui_stack.normalization 3 [0, 4] integer index of the normalization method
gui_stack.rejection 5 [0, 7] integer index of the rejection method
gui_stack.weighting 0 [0, 4] integer index of the weighting method
gui_stack.sigma_low 3 [0, 20] double sigma low value for rejection
gui_stack.sigma_high 3 [0, 20] double sigma high value for rejection
gui_stack.linear_low 5 [0, 20] double linear low value for rejection
gui_stack.linear_high 5 [0, 20] double linear high value for rejection
gui_stack.percentile_low 3 [0, 100] double percentile low value for rejection
gui_stack.percentile_high 3 [0, 100] double percentile high value for rejection
gui.first_start (not set) string first start of siril
gui.silent_quit false boolean don't confirm quit when exiting
gui.silent_linear false boolean don't confirm save when non linear mode
gui.remember_windows true boolean remember window position
gui.main_win_pos_x 0 integer main window position
gui.main_win_pos_y 0 integer main window position
gui.main_win_pos_w 0 integer main window position
gui.main_win_pos_h 0 integer main window position
gui.pan_position -1 integer position of the two sides separator
gui.extended true boolean main window is extended
gui.maximized false boolean main window is maximized
gui.theme 0 [0, 1] integer index of the selected theme
gui.font_scale 100 double font scale in percent
continues on next page

3.2. Preferences (commands) 51

Siril, Release 1.2.0

Table 1 – continued from previous page

Variable Default Type Comment
([Range])
gui.icon_symbolic false boolean icon style
gui.script_path list of list of script directories
strings
gui.warn_script_run true boolean warn when launching a script
gui.show_thumbnails true boolean show thumbnails in open dialog
gui.thumbnail_size 256 integer size of the thumbnails
gui.selection_guides 0 integer number of elements of the grid guides
gui.show_deciasec false boolean show tenths of arcseconds on hover
gui.default_rendering_mode 0 [0, 6] integer default display mode
gui.display_histogram_mode 0 [0, 1] integer default histogram display mode
gui.color_bkg_samples rgba(255, 51, string configure background samples color
26, 1.0)
gui.color_std_annotations rgba(128, 255, string configure standard annotation color
77, 0.9)
gui_astrometry.compass_position 1 [0, 5] integer index of the compass position over grid
gui_astrometry.cat_messier true boolean show Messier objects in annotations
gui_astrometry.cat_ngc true boolean show NGC objects in annotations
gui_astrometry.cat_ic true boolean show IC objects in annotations
gui_astrometry.cat_ldn true boolean show LDN objects in annotations
gui_astrometry.cat_sh2 true boolean show SH2 objects in annotations
gui_astrometry.cat_stars true boolean show stars in annotations
gui_astrometry.cat_user true boolean show user objects in annotations
gui_pixelmath.pm_presets list of list of pixel math presets
strings

(*). For kstars catalogues, this will default to ~/.local/share/kstars/, irrespective of your OS.
In any case, you will need to download them and set the path you've chosen.
See section about using local catalogues.

The values can be fetched with get command:

Siril command line

get { -a | -A | variable }

Gets a value from the settings using its name, or list all with -a (name and value list) or with -A (detailed list)

See also SET to update values

Links: set

The values can be modified with set command:

52 Chapter 3. Preferences
 Siril, Release 1.2.0

Siril command line

set { -import=inifilepath | variable=value }

Updates a setting value, using its variable name, with the given value, or a set of values using an existing ini file with
-import= option.
See GET to get values or the list of variables

Links: get

3.2. Preferences (commands) 53

Siril, Release 1.2.0

54 Chapter 3. Preferences
 CHAPTER

FOUR

FILE FORMATS

There are several file formats that Siril can open and work on. However, only two are read natively and allow to build
sequences: the FITS and SER formats.
Here we will look at the different file formats read by Siril and understand the limitations of some and the strengths of
others.

4.1 Bit Depth

The bit depth, defines the number of bits used to indicate the color of a single pixel, or the number of bits used for each
color component of a single pixel.
For images of daily life, 8-bit is more than enough. This means that a pixel is encoded on values in the range [0, 255].
However, photographing astronomical objects is more demanding and usually requires working on images with a bit
depth of at least 16-bit: i.e. in the range [0, 65535]. Even better, 32-bit precision allows the most subtle information to
be retained. On this last type, the pixels are either encoded in the interval [0, 4294967295], or, as used in Siril, between
the floating values [0, 1]. It is possible to find formats encoding pixels on 64-bit (in the range [0, 1], but they are rare
and have a very specific use. In particular the FITS format allows this.
However, not all image file formats support 16-bit, let alone 32-bit. This must therefore be taken into account when
choosing a format to work with.

4.2 Common File Formats

The image file formats presented here are standard formats, readable by all image manipulation software. These formats
were designed to meet the needs some time ago and may be obsolete. Moreover, none of these formats have been
designed to handle astronomical data. They must therefore generally be used at the end of the processing chain.

4.2.1 BMP Format

Files with the .bmp extension are bitmap image files used to store digital bitmap images. These images are independent
of the graphics card and are also called Device Independent Bitmap (DIB) file format. This independence allows the
file to be opened on multiple platforms such as Microsoft Windows and Mac. The BMP file format allows data to be
stored as two-dimensional digital images, both in monochrome and in color, with different color depths.
Nowadays, this format is not really used anymore and other file types are preferred.

55
Siril, Release 1.2.0

Fig. 1: Linear image saved in 16-bit

56 Chapter 4. File Formats

 Siril, Release 1.2.0

Fig. 2: The same linear image saved in 8-bit. Almost all data have been lost

4.2. Common File Formats 57

Siril, Release 1.2.0

4.2.2 JPEG Format

Probably the most used file format for sharing images on forums, by e-mail or usb sticks. This format allows a more
or less strong (destructive) compression which gives ideal file sizes for exchanges. The extension of this type of file is
.jpg or .jpeg.
The JPEG format is however only coded in 8-bit. With the compression that produces artifacts, this format is not very
suitable for astronomy images and we generally prefer the PNG format.

4.2.3 PNG Format

Portable Network Graphics is a raster-graphics file format that supports lossless data compression. The extension of
the format is .png. PNG grayscale images support the widest range of pixel depths of any image type. Depths of 1, 2,
4, 8, and 16-bit are supported, covering everything from simple black-and-white scans to full-depth medical and raw
astronomical images.
Calibrated astronomical image data is usually stored as 32-bit or 64-bit floating-point values, and some raw data is
represented as 32-bit integers. Neither format is directly supported by PNG.
However, this format is an excellent choice for saving the final image, after processing.

4.2.4 TIFF Format

TIFF or TIF, Tagged Image File Format, represents raster images for use on various devices that conform to this file
format standard. It is capable of describing bi-level, grayscale, palette color and full color image data in multiple color
spaces. It supports both lossless and lossy compression schemes to allow applications that use this format to choose
between space and time. The extension is either .tiff or .tif.
The advantages of the TIFF format are multiple. It supports encoding up to 32-bit per pixel and offers a wide variety
of possible fields in the metadata making it a good candidate for storing astronomical data.
Using the TIFF format, and in collaboration with other developers, we have set up a pseudo standard, Astro-TIFF.

4.2.5 NetPBM Format

Several graphics formats are used and defined by the Netpbm project. The portable pixmap format (PPM), the portable
graymap format (PGM) and the portable bitmap format (PBM) are image file formats designed to be easily exchanged
between platforms. Possible file extension are .pbm, .pgm (for gray scale files) and .ppm.
These formats, supporting up to 16-bit per channel, are marginally used and should only be used for final image storage.

4.2.6 AVI format

It's a film container, able to contain data with various audio and video codecs. Some lossless video codecs exist and
they have been used for astronomy imaging purposes in the past, but it's a format that does not contain metadata usable
for astronomy, that is limited to 8-bit images and that does not give any warranty that the data it contains is raw.

Warning: This input file format is now deprecated. We recommend to use SER format instead.

58 Chapter 4. File Formats

 Siril, Release 1.2.0

4.3 FITS

4.3.1 Specification

FITS stands for Flexible Image Transport System and is the standard astronomical data format used by professional
scientists such as NASA. FITS is much more than an image format (such as JPG or TIFF) and is primarily designed to
store scientific data consisting of multidimensional arrays.
A FITS file consists of one or more header and data units (HDUs), with the first HDU referred to as the "primary HDU"
or "primary array." Five primary data types are supported: 8-bit unsigned bytes, 16 and 32-bit signed integers, and 32
and 64-bit single and double-precision floating-point reals. The FITS format can also store 16 and 32-bit unsigned
integers.
Each header unit consists of any number of 80-character keyword records which have the general form:

KEYNAME = value / comment string

The keyword names may be up to 8 characters long and can only contain uppercase letters, the digits 0-9, the hyphen,
and the underscore character. The keyword name is (usually) followed by an equals sign and a space character (= ) in
columns 9 - 10 of the record, followed by the value of the keyword which may be either an integer, a floating point
number, a character string (enclosed in single quotes), or a boolean value (the letter T or F).
The last keyword in the header is always the END keyword which has no value or comment fields.
Each header unit begins with a series of required keywords that specify the size and format of the following data unit.
A 2-dimensional image primary array header, for example, begins with the following keywords:

SIMPLE = T / file does conform to FITS standard

BITPIX = 16 / number of bits per data pixel
NAXIS = 2 / number of data axes
NAXIS1 = 440 / length of data axis 1
NAXIS2 = 300 / length of data axis 2

Note: In Siril, 64-bit FITS files are not supported. Siril reads them but converts them to 32-bit files.

4.3.2 Compression

Compression is the way to reduce the size of the image. There are many methods of compression depending on the
type of images used. This compression can be destructive, as with the JPEG, or lossless as proposed by the PNG.
It is possible to work with compressed FITS files. At the cost of a longer calculation time, the size of the images can
be reduced considerably. Siril offers several compression algorithms which are the following:
• Rice: The Rice algorithm is simple and very fast
• GZIP 1: The gzip algorithm is used to compress and uncompress the image pixels. Gzip is the compression
algorithm used in the free GNU software utility of the same name.
• GZIP 2: The bytes in the array of image pixel values are shuffled into decreasing order of significance before
being compressed with the gzip algorithm. This is usually especially effective when compressing floating-point
arrays.
One option is associated to these algorithms, the Quantization level:
While floating-point format images may be losslessly compressed (using gzip, since Rice only compresses integer
arrays), these images often do not compress very well because the pixel values are too noisy; the less significant bits

4.3. FITS 59
Siril, Release 1.2.0

in the mantissa of the pixel values effectively contain incompressible random bit patterns. In order to achieve higher
compression, one needs to remove some of this noise, but without losing the useful information content. If it is too
large, one undersamples the pixel values resulting in a loss of information in the image. If it is too small, however, it
preserves too much of the noise (or even amplifies the noise) in the pixel values, resulting in poor compression.

Note: The supported image compression algorithms are all loss-less when applied to integer FITS images; the pixel
values are preserved exactly with no loss of information during the compression and uncompression process. Floating
point FITS images (which have BITPIX = -32 or -64) are first quantized into scaled integer pixel values before
being compressed. This technique produces much higher compression factors than simply using GZIP to compress
the image, but it also means that the original floating value pixel values may not be precisely returned when the image
is uncompressed. When done properly, this only discards the 'noise' from the floating point values without losing any
significant information.

4.3.3 Orientation of FITS images

The FITS standard is a container that describes how to store image data and metadata. Professional tools, from the early
age of the FITS format, like ds9 (Harvard Smithsonian Center for Astrophysics), fv (FITS viewer from NASA), store
images bottom-up. We might be tempted to say that it does not really matter, but when demosaicing or astrometry is
involved, problems arise. For example, the usual RGGB Bayer pattern becomes GBRG if the image is upside-down.
Nowadays, despite this, most camera drivers are writing data in the top-down order and we have to cope with it.
For these reasons, we recently have introduced, together with P. Chevalley of CCDCiel, a new FITS keyword. We
encourage all data producers, INDI and ASCOM developers, to use it in order to make things easier for everybody.
This keyword is ROWORDER of type TSTRING. It can take two values: BOTTOM-UP and TOP-DOWN.
Siril will always read and display images in the bottom-up order, however if the top-down information is specified in
the keyword, then Siril will demosaic the image with the corrected pattern.

Why would some programs write images bottom-up in the first place?

The reason is: mathematics do it that way.

Also, the FITS specification says:

5.1. Image display conventions

It is very helpful to adopt a convention for the display of images transferred via the FITS format. Many of the current
image processing systems have converged upon such a convention. Therefore, we recommend that FITS writers order
the pixels so that the first pixel in the FITS file (for each image plane) be the one that would be displayed in the lower-left
corner (with the first axis increasing to the right and the second axis increasing upwards) by the imaging system of
the FITS writer. This convention is clearly helpful in the absence of a description of the world coordinates. It does
not preclude a program from looking at the axis descriptions and overriding this convention, or preclude the user from
requesting a different display. This convention also does not excuse FITS writers from providing complete and correct
descriptions of the image coordinates, allowing the user to determine the meaning of the image. The ordering of the
image for display is simply a convention of convenience, whereas the coordinates of the pixels are part of the physics
of the observation.

Warning: ROWORDER keyword can be used for:

1. Displaying the image with the intended orientation (unflip the display).

60 Chapter 4. File Formats

 Siril, Release 1.2.0

2. Unflip the Bayer demosaic pattern. So the demosaic pattern can be specified conform the sensor supplier.
BUT
1. ROWORDER shall not be used to unflip the image data for stacking. Otherwise new images would become
incompatible with older darks and flats.
2. ROWORDER shall not be used to unflip the image data for astrometric solving. This would make the astrometric
solution incompatible with other programs.

4.3.4 Software using this keyword

• Siril (since version 0.99.4)

• CCDCiel (since version 0.9.72)
• Indi (since Jul. 2020)
• KStars (since 3.4.3)
• SharpCap (since version 3.3)
• FireCapture (since version 2.7)
• N.I.N.A (since version 1.10)
• MaxImDL (since version 6.23)
• INDIGO (since Jul. 2020)
• PixInsight (since version 1.8.8-6)
• ASTAP (since version ß0.9.391)
• APT (since version 3.86.3)
• AstroDMx Capture (since version 0.80)
• Astroart (since version 8.0)

4.3.5 Retrieving the Bayer matrix

Image row order changes the way the Bayer matrix should be read, but there are also two optional FITS header keywords
that have an effect on this: XBAYROFF and YBAYROFF. They specify an offset to the Bayer matrix, to start reading it on
first column or first row.
To help developers integrating the ROWORDER, XBAYROFF and YBAYROFF keywords in their software, some test images
were created by Han Kleijn from hnsky.org, one for each combination of the three keywords. Download them here:
Bayer_test_pattern_v6.tar.gz.

4.3. FITS 61
Siril, Release 1.2.0

4.3.6 List of FITS keywords

Siril can read and interpret a wide range of keywords. The following list illustrates the non-standard keywords that Siril
registers if necessary. Some keywords read by Siril may not appear in this list. For example, the keywords CCDTEMP
or TEMPERAT, that indicate the temperature of the sensor, are correctly read, but are propagated under the keyword
CCD-TEMP.

Table 1: FITS keywords saved by Siril

FITS Keyword Type Comment
MIPS-HI Unsigned short Upper visualization cutoff
MIPS-LO Unsigned short Lower visualization cutoff
MIPS-FHI Float Upper visualization cutoff
MIPS-FLO Float Lower visualization cutoff
BZERO Double Offset data range to that of unsigned short
BSCALE Double Default scaling factor
ROWORDER String Order of the rows in image array
INSTRUME String Instrument name
TELESCOP String Telescope used to acquire this image
OBSERVER String Observer name
DATE String UTC date that FITS file was created
DATE-OBS String YYYY-MM-DDThh:mm:ss observation start, UT
STACKCNT Unsigned int Stack frames
EXPTIME Double Single Frame exposure time [s]
LIVETIME Double Total exposure time [s]
EXPSTART Double Exposure start time (standard Julian date)
EXPEND Double Exposure end time (standard Julian date)
XPIXSZ Float X pixel size microns
YPIXSZ Float Y pixel size microns
XBINNING Unsigned int Camera binning mode
YBINNING Unsigned int Camera binning mode
FOCALLEN Double Camera focal length
CCD-TEMP Double CCD temp in C
SET-TEMP Double Temperature setting in C
FILTER String Active filter name
IMAGETYP String Type of image
OBJECT String Name of the object of interest
APERTURE Double Aperture of the instrument
ISOSPEED Double ISO camera setting
BAYERPAT String Bayer color pattern
XBAYROFF Int X offset of Bayer array
YBAYROFF Int Y offset of Bayer array
GAIN Unsigned short Camera gain
OFFSET Unsigned short Camera offset
CVF Double Conversion factor (e-/adu)
AIRMASS Double Airmass
SITELAT Double [deg] Observation site latitude
SITELONG Double [deg] Observation site longitude
SITEELEV Double [m] Observation site elevation
DFTTYPE String Module/Phase of a Discrete Fourier Transform
DFTORD String Low/high spatial freq. are located at image center
DFTNORMX String Normalisation value for channel #X
PROGRAM String Software that created this HDU
continues on next page

62 Chapter 4. File Formats

 Siril, Release 1.2.0

Table 1 – continued from previous page

FITS Keyword Type Comment
CTYPE1 String Coordinate type for the first axis
CTYPE2 String Coordinate type for the second axis
CUNIT1 String Unit of coordinates
CUNIT2 String Unit of coordinates
EQUINOX Double Equatorial equinox
CTYPE3 String RGB image
OBJCTRA String Image center Right Ascension (hms)
OBJCTDEC String Image center Declination (dms)
RA Double Image center Right Ascension (deg)
DEC Double Image center Declination (deg)
CRPIX1 Double Axis1 reference pixel
CRPIX2 Double Axis2 reference pixel
CRVAL1 Double Axis1 reference value (deg)
CRVAL2 Double Axis2 reference value (deg)
CDELT1 Double X pixel size (deg)
CDELT2 Double Y pixel size (deg)
PC1_1 Double Linear transformation matrix (1, 1)
PC1_2 Double Linear transformation matrix (1, 2)
PC2_1 Double Linear transformation matrix (2, 1)
PC2_2 Double Linear transformation matrix (2, 2)
CD1_1 Double Scale matrix (1, 1)
CD1_2 Double Scale matrix (1, 2)
CD2_1 Double Scale matrix (2, 1)
CD2_2 Double Scale matrix (2, 2)
PLTSOLVD Logical Siril solver

4.4 Astro-TIFF

In 2022, Han Kleijn, developer of the ASTAP software, offered to contribute to the development of a new pseudo-
standard using the TIFF format and taking advantage of the power of FITS file headers. This is how the Astro-TIFF
format was born.

4.4.1 Why a new standard among all the others?

Currently, the most used format for astrophotography is the FITS format. This one, developed by processional scientists,
meets all the expectations of amateurs. And although its great flexibility causes some concerns of compatibility it
remains the format to be preferred.
Other specialized formats exist but are usually associated with a specific software. Like the XISF format developed by
the PixInsight team. This last format, although often requested in Siril, is a format dedicated to PixInsight, a proprietary
software. So the interest in developing compatibility with Siril is minimal, and we've only done it for reading in the
1.4.x cyle.
Developing Astro-TIFF appears then as a good alternative, because based on the TIFF format, it is possible to open the
files on any image processing software.
Finally, the TIFF format supports compression (as does the FITS format) which allows for smaller image sizes.

4.4. Astro-TIFF 63
Siril, Release 1.2.0

4.4.2 Specification 1.0

Dated 2022-06-21

• Files are following the TIFF 6.0 specification including supplement 2 fully.
• The FITS header is written to the TIFF baseline tag Image Description. Code 270, Hex 010E.
• The header is following the FITS specification except that that the lines can be shorter then 80 characters and
lines are ending with either CR+LF (0D0A) or LF (0A).
• First line in the description is the first header line and starts with SIMPLE. The last line of the header starts with
END.

Recommendations

• TIFFtag_orientation=1 (left-top) Orientation is following the conventions. Pixel FITS_image[1,1] is left-

bottom. TIFF_image[0,0] is left-top. These pixels are first written or read from the file. So when writing a
FITS image into TIFF preserving the orientation for the user, the first pixel to write is FITS_image[1,NAXIS2].
• TIFFtag_compression=8 (Deflate) or 5 (LZW).
• For greyscale images TIFFtag_PhotometricInterpretation = 1 (minimum value is black, maximum is
white).
• Write all available header keywords.

Notes
• This use of TIFF format is intended for 16-bit lights, darks, flats and flat-darks (astronomical images), but can
also be used in the 32-bit format. It is possible to convert FITS to TIFF and backwards but the application
programmer can decide to export only (write) or only import (read) in Astro-TIFF format.
• If an astrometrical (plate) solution is included then it should match with the image orientation.
• Some header keywords are redundant like NAXIS1, NAXIS2, BZERO and BITPIX and are not required. TIFF
image dimensions and type are leading.
• The de-mosaic pattern specified in the header should match with the image orientation.
• The header will be visible in many image manipulation programs.

Example of an Astro-TIFF header that looks just like a FITS file header:

SIMPLE = T / file does conform to FITS standard

BITPIX = -32 / number of bits per data pixel
NAXIS = 2 / number of data axes
NAXIS1 = 6248 / length of data axis 1
NAXIS2 = 4176 / length of data axis 2
NAXIS3 = 1 / length of data axis 3
EXTEND = T / FITS dataset may contain extensions
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy
COMMENT and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H
BZERO = 0 / offset data range to that of unsigned short
BSCALE = 1 / default scaling factor
DATE = '2022-12-14T16:05:47' / UTC date that FITS file was created
DATE-OBS= '2022-05-06T20:29:20.019000' / YYYY-MM-DDThh:mm:ss observation start,
(continues on next page)

64 Chapter 4. File Formats

 Siril, Release 1.2.0

(continued from previous page)

INSTRUME= 'ZWO CCD ASI2600MM Pro' / instrument name
OBSERVER= 'Unknown ' / observer name
TELESCOP= 'iOptron ZEQ25' / telescope used to acquire this image
ROWORDER= 'TOP-DOWN' / Order of the rows in image array
XPIXSZ = 3.76 / X pixel size microns
YPIXSZ = 3.76 / Y pixel size microns
XBINNING= 1 / Camera binning mode
YBINNING= 1 / Camera binning mode
FOCALLEN= 370.092 / Camera focal length
CCD-TEMP= -9.8 / CCD temp in C
EXPTIME = 120 / Exposure time [s]
STACKCNT= 126 / Stack frames
LIVETIME= 15120 / Exposure time after deadtime correction
FILTER = 'Lum ' / Active filter name
IMAGETYP= 'Light Frame' / Type of image
OBJECT = 'Unknown ' / Name of the object of interest
GAIN = 100 / Camera gain
OFFSET = 50 / Camera offset
CTYPE1 = 'RA---TAN' / Coordinate type for the first axis
CTYPE2 = 'DEC--TAN' / Coordinate type for the second axis
CUNIT1 = 'deg ' / Unit of coordinates
CUNIT2 = 'deg ' / Unit of coordinates
EQUINOX = 2000 / Equatorial equinox
OBJCTRA = '09 39 54.932' / Image center Right Ascension (hms)
OBJCTDEC= '+70 00 10.118' / Image center Declination (dms)
RA = 144.979 / Image center Right Ascension (deg)
DEC = 70.0028 / Image center Declination (deg)
CRPIX1 = 3123.5 / Axis1 reference pixel
CRPIX2 = 2088.5 / Axis2 reference pixel
CRVAL1 = 144.979 / Axis1 reference value (deg)
CRVAL2 = 70.0028 / Axis2 reference value (deg)
CD1_1 = -0.000580606 / Scale matrix (1, 1)
CD1_2 = -4.12215e-05 / Scale matrix (1, 2)
CD2_1 = -4.11673e-05 / Scale matrix (2, 1)
CD2_2 = 0.000580681 / Scale matrix (2, 2)
PLTSOLVD= T / Siril internal solve
HISTORY Background extraction (Correction: Subtraction)
HISTORY Plate Solve
END

4.4.3 Saving Astro-TIFF in Siril

In Siril you can save Astro-TIFF files by choosing the TIFF format in the save dialog when you click on Save As.
The drop-down list in the TIFF dialog allows you to choose between saving in standard TIFF format or in Astro-TIFF
format. The latter is the default format.

Siril command line

savetif filename [-astro] [-deflate]

4.4. Astro-TIFF 65
Siril, Release 1.2.0

Fig. 3: Save Dialog with Astro-TIFF option

66 Chapter 4. File Formats

 Siril, Release 1.2.0

Saves current image under the form of a uncompressed TIFF file with 16-bit per channel: filename.tif. The option
-astro allows saving in Astro-TIFF format, while -deflate enables compression.

See also SAVETIF32 and SAVETIF8

4.4.4 Sample files

• Astro-TIFF file created by Siril (32-bit, uncompressed).

• Astro-TIFF file created by Siril (32-bit, compressed).

4.5 SER

SER file format is a simple image sequence format, similar to uncompressed films. Documentation can be found on
the official page. The latest PDF document is mirrored on free-astro too.
With improvements of version 2 and 3, SER handles colour images, which makes it perfect as replacement for the usual
AVI or other film format produced by older capture programs in all astronomy situations. Compressed images should
not be used for astronomy but can still be converted to SER, which will make the files bigger for the same quality, but
easier to work with.
Siril can convert any image sequence and many film formats into SER files. Ser-player is a great tool that allows SER
files to be visualised just like any film, with many options and works on most operating systems.
The main issue with AVI and other film containers is that it is designed to work with many codecs and pixel formats,
which it good for general purpose films, but requires astronomy software to handle a large array of actually different
file formats. General purpose film software are often not well equipped to handle 16-bit per pixel values or some
uncompressed data formats. With SER, only one file format handles it all, that's why Siril for example is now developing
processing only for SER.

4.5.1 File structure

A SER file has three parts:

• a 178-byte header containing images and observation information
• image data, raw pixel data
• an optional trailer containing dates for all images of the sequence

4.5.2 Handling colours

In version 3 (2014), there are two ways of handling coloured images in SER. If data comes directly from a sensor, the
preferred way is probably to use one-plane images and interpolating data from the colour filter array (similarly to CFA
file formats used in astronomy software).
The other way, added in version 3, is to use three planes to represent RGB image data. SER v3 supports RGB/BGR
8/16-bit data. This can be useful if data is converted from a source with an unknown colour filter array or for general
purpose conversion.

4.5. SER 67
Siril, Release 1.2.0

4.5.3 Specification issue with endianness

Since SER files can contain 16-bit precision images, endianness must be well specified. The specification allows
endianness to be either big-endian or little-endian, to facilitate file creation on various systems, as long as the used
endianness is documented in the file's header.
For an unknown reason, several of the first programs to support SER disrespect the specification regarding the en-
dianness flag. The specification states that a boolean value is used for the LittleEndian header, and they use it as a
BigEndian header, with 0 for little-endian and 1 for big-endian. Consequently, to not break compatibility with these
first implementations, later programs, like Siril, GoQat, Ser-player and many others, have also decided to implement
this header in opposite meaning to the specification.

4.6 IRIS PIC

The PIC format is a proprietary image format created for Christian Buil's IRIS software. To ensure compatibility with
the latter, Siril is able to read this type of file. However, because the format is proprietary and the specifications are not
known, not all header information will be saved when converting to FITS.
Siril cannot record in PIC format.

68 Chapter 4. File Formats

 CHAPTER

FIVE

SEQUENCES

Sequences are what Siril uses to represent a set of manipulated files, for example the set of dark images that we'll turn
into the master dark. It is a very useful tool for handling a large number of files that need to be linked with each other.

5.1 A set of two or more FITS files

Siril uses natively 32-bit floating point data or 16-bit unsigned integer data for the FITS images, other formats are
automatically converted. To be recognized and detected as a sequence, FITS images file names must respect a particular
pattern which is:

basename$i.[ext]

• basename can be anything using ascii characteres. It is usually convenient, but not mandatory, to have it end
with the _ character. It will be used as the sequence name.
• $i is the index of the image. It must be a positive number and can have several leading zeros.
• [ext] is the supported extension as explained in the settings, fit by default.

Note: The extension used to detect FITS sequences in the current working directory will be the same as the extension
configured in the settings and as the files created by Siril.

Warning: Some operating systems limit the number of images that can be opened at the same time, which is
required for median or mean stacking methods. For Windows, the limit is 2048 images. If you have a lot of images,
you should use another type of sequence, described below.

5.2 A single SER file

SER is a format meant to contain an acquisition sequence of several contiguous images in a single file. It is a rather
simple format that cannot contain as much metadata as FITS, but more than simple films and data is not compressed.
SER files can contain images of 8 or 16-bits per channel only. There are three types of SER files, depending on the
pixel content: monochrome, CFA or color (3 channels).

Note: An SER file can be opened either via File and Open, or with the Search sequences button.

69
Siril, Release 1.2.0

See SER for more information on the SER format and why film formats like uncompressed AVI should not be used for
astronomy.

Warning: To some extent, a regular film file such as AVI or any other container are supported too. Film files
support is being dropped in favour of SER, but it can still be useful to open a film in Siril, to explore its content,
extract some frames or convert them. A few operations can still be done, but in a slower way than with other
sequences, like sum stacking. For a complete processing you will face limitations and incompatibilities.

5.3 A single FITS file

Note: Also called FITS cubes or FITS sequences, or FITSEQ for short in Siril.

The FITS format is an image and science data container, it can contain several of these in a single file. We can use that
to store an entire sequence of FITS images in a single file while preserving the FITS header of each image. It is the file
format that professional astronomers use.
It's simpler to manage one file on the disk than 2000, but since it is a single file, some operations on single images
of the sequence may not be possible. In particular, it is not currently supported within Siril to change the header of a
single image.
This format is an alternative to SER for a single-file sequence, with 32 bits per channel and full header support.

5.4 Loading a sequence

Fig. 1: Sequence Search and Cleaning.

When the working directory is set in the right place, the FITS follow the correct nomenclature, and the extension of
the FITS files is also set correctly, then click the Search Sequence button of the Sequence tab. A drop-down list opens
with all the sequences available in the folder. If only one is found, then it is automatically selected and loaded.

5.5 Frame selector

A great strength of Siril is that it easily manipulates image sequences. When a sequence is opened, the reference image
(see below) will be displayed, by default this is the first image. However, it can sometimes be useful to inspect individual

images of a sequence. This is possible with the frame selector, available via the toolbar with the button or via
the sequence tab with the Open Frame List button.
Clicking on an image in the list will load it and display it in the main area, while keeping the sequence as the active
object for processing. More than just a image display selector, the tool can also be used to manually exclude images

70 Chapter 5. Sequences
 Siril, Release 1.2.0

Fig. 2: Frame selector that allows you to choose a frame from the sequence and display it, set it as reference or exclude
it.

from the sequence, or visualize which are still included, visualize the values of image quality and shift between images
if they have been computed, and change the reference image. Note that more image quality information can be viewed
in the Plot tab.
Excluding an image from the sequence does not mean its data will be permanently deleted, it will just not be used for
the subsequent processing operations, if instructed to do so. In most cases, the option to look for is called Process
included images only.
The reference image is the image in the sequence that will serve as target for the registration and for the normalization.
Other images will be transformed to look like the reference image, so it should be chosen carefully. Fortunately, since
Siril 1.2, a new two-pass registration can automatically select the best image of the sequence as reference image before
proceeding to image transformation.
The header bar of the window will provide many controls for these sequence properties:
• The drop-down menu allows the channel for which registration data (quality, shifts) is displayed to be changed,
if they exist for other channels.
• The first button of the toolbar sets all images of the sequence as manually excluded.
• The second one, sets them all as included.

Siril command line

select sequencename from to

This command allows easy mass selection of images in the sequence sequencename (from from to to included).
This is a selection for later processing.

5.5. Frame selector 71

Siril, Release 1.2.0

See also UNSELECT

Links: unselect

Siril command line

unselect sequencename from to

Allows easy mass unselection of images in the sequence sequencename (from from to to included). See SELECT

Links: select

• The third includes or excludes the images selected from the list (multiple selections can be done with Ctrl or
Shift) of the sequence.
• The last button can be deactivated to not show the red rectangle over registered images. It represents the framing
of the reference image as computed by the registration.
• The button Reference image is used to select the reference image for the sequence. All sequences must have one,
it will be the first image if unset or by default.

Siril command line

setref sequencename image_number

Sets the reference image of the sequence given in first argument. image_number is the sequential number of the
image in the sequence, not the number in the filename, starting at 1

• Finally, the search field allows you to find the images by name.
It is also possible to sort all the images by clicking on the column headers. Thus you can sort the images by their name,
their number, their X/Y offset or their FWHM. The latter is very useful to have a look at the best and worst images.

5.6 Sequence export

The Sequence Export tool allows you to export a sequence of images in a variety of formats. It is particularly useful if
you want to export the images taking into account the registration information contained in the seq file, with optional
cropping and normalization.
With the sequence export function, you can select a sequence to export, choose the file format and compression level
for video formats. Siril's sequence export function supports a wide range of image file formats, including FITS (single
FITS file or sequence FITS file), TIFF, SER , AVI, MP4 and WEBM and can come in handy when building timelapse.

72 Chapter 5. Sequences
 Siril, Release 1.2.0

Fig. 3: Give a name and specify output format to export a sequence.

The button Normalize images allows you to normalize the images with respect to the reference image. The normalization
is the same as the one done during the stacking, with the following settings: Additive with scaling, Faster normalization
disabled.
Moreover, it is possible to play with the image filtering criteria to exclude or not images according to their quality. A
button Go to the stacking tab has been added here, to easily go to the tab that exposes them.

5.7 Sequence information

All sequence information, registration transformation, statistics and frame selection are stored in a .seq file saved next
to the sequence files. It is strongly recommended never to edit this file manually because Siril writes continuously
inside it and one wrong character could make the reading of the sequence corrupt.
One way to clean the content of this sequence file is to go in the Sequence tab and click on Clean Sequence. The choice
of what will be cleaned can be defined by clicking on the small arrow next to it.

Fig. 4: Menu to clean the sequence file.

Siril command line

seqclean sequencename [-reg] [-stat] [-sel]

This command clears selection, registration and/or statistics data stored for the sequence sequencename.

You can specify to clear only registration, statistics and/or selection with -reg, -stat and -sel options respectively. All
are cleared if no option is passed

5.7. Sequence information 73

Siril, Release 1.2.0

74 Chapter 5. Sequences
 CHAPTER

SIX

DEFINITIONS AND WORKFLOW

Astrophotography is the process of capturing images of celestial objects. It involves several steps, including prepro-
cessing and processing, which are distinct but related.
Preprocessing is the initial step of working with raw astrophotographic data. It involves preparing these data for further
processing. This step typically involves dark current subtraction, flat field correction, and correction of other basic
problems such as removing hot and cold pixels.
Processing refers to the post-processing of the preprocessed data, generally after stacking. This is where the astropho-
tographer applies various techniques to enhance the final image and bring out details and features. These may include
sharpening (deconvolution), color calibration, noise reduction, and stretching the image to increase the visibility of
faint details.
In short, preprocessing sets the stage for processing by ensuring that the data is in an appropriate form and cleaned of
unwanted signal, while processing is about bringing out the best in the signal to create the final image. Both steps are
important in the astrophotography process, and the quality of the result depends on the skills and techniques applied at
both stages.
In Siril, the main preprocessing is done following the order of the tabs in the right pane and requires the use of master
files. This is a process that can be automated quite easily and the scripts provided in Siril perform this task. The image
processing is processed via the dedicated menu Image Processing. This process is more difficult to automate because
it is specific to each image and consists of an iterative work.

75
Siril, Release 1.2.0

76 Chapter 6. Definitions and workflow

 CHAPTER

SEVEN

PREPROCESSING

This section takes you through the different steps of pre-processing your images, from import into Siril to obtaining a
stacked image.
The right pane contains the tabs that are useful during preprocessing. They have been designed to be used from left to
right throughout the process, with some exception for the creation of masters. These tabs are also accessible via the
keys F1 to F7.
Pre-processing is the step that starts with the conversion to the stacking of the images. The goal is to remove all
unwanted signals and to reduce the noise present on all the subs.

7.1 Conversion

Siril supports the FITS 32bits format as well as the SER format in a native way. Therefore, any other file format must
first be converted to these formats in order to be supported and to generate a sequence. The type of supported files is
indicated in the tab and depends on how Siril was compiled.
Siril provides a conversion tab which is divided into 2 panels. The upper panel allows you to load the source files you
wish to convert.

The management of these files is done from the mini toolbar .

• The first button, the + button, is the one that allows to load all the source files. It opens a dialog window allowing
you to choose all the files to be converted on your computer. Only the formats supported by Siril are visible.

Tip: It is possible to drag and drop files directly into the sources area. The drop zone is highlighted when the
files are over it.

• The second button, the - button, allows to delete the selected files. Several files can be deleted at the same time.
They are not deleted from the hard disk, but only from the conversion area.
• The last button allows you to delete all loaded files at once.
The number of loaded and selected files are reported in the status bar, to the right of the toolbar.
In the destination section it is possible to choose the name of the sequence that will be generated after the conversion
of the files.
Thus, for a sequence name basename, the converted files will be of the form

basenameXXXXX.[ext]

77
Siril, Release 1.2.0

Fig. 1: Image 1 shows the result of the conversion of a raw digital camera image. You can see visible dust, similar to
dark spots. Image 2, after calibration of the images by the master darks, bias and flats shows the complete removal of
these spots and a cleaner signal. Image 3 is the same after demosaicing, showing color and a very large green cast due
to the higher sensitivity of the green photosites on the sensors. Finally, image 4 is the stacking output, with channel
balancing.

78 Chapter 7. Preprocessing
 Siril, Release 1.2.0

Fig. 2: Source panel of the conversion tab.

Fig. 3: Destination panel of the conversion tab.

7.1. Conversion 79
Siril, Release 1.2.0

The extension is as defined in the preferences. The XXXXX index starts by default at 00001 with the first image, however
it is possible to define a different starting index. This can be useful in the case of a multi-session that shares the same
master files. Three types of outputs are possible, to choose from a drop-down menu:
• FITS images
• SER sequence
• FITS sequence
These file formats are explained in the sequence section of this documentation.
Technically, when the input files are in FITS format, there is no need to convert them. However, you may want to do
so so that the files are renamed to create a sequence and can be processed in Siril. In order not to fill the hard disk
unnecessarily, it is then possible to choose the option Symbolic link. This option creates a symbolic link for the FITS
files instead of copying them. This option is therefore only available when the output files are FITS images.

Note: When symbolic links are enabled, this disables compression.

Warning: For Microsoft Windows, the use of symbolic links requires the activation of the developer mode in
Windows.

Warning: If on GNU/Linux you see the error Symbolic link Error: Function not implemented could be because
you try making a symlinked sequence in a directory on a filesystem that doesn't permit symbolic links.

When the output formats are SER, or FITS sequence, then the Multiple sequences option becomes visible. Tick this
to create several sequence files instead of a single SER or FITS file for all input elements. Use this if input elements
(sequence files such as films, SER or FITS cubes) don't share the same image size or must not be processed together.
The last option Debayer allows the user to demosaic the images during the conversion. This option should generally
not be used if the images are bias, dark and flat images, or light images intended to be pre-processed. Indeed, due
to Bayer matrix consideration, the RGB result of your RAW image is an interpolated picture. In consequence pre-
processing interpolated data will give wrong results. Converting RAW files of an OSC sensor gives Color Filter Array
(CFA) monochrome FITS pictures. Contrary to RGB image, CFA image represent the entire sensor data with the Bayer
pattern. The following image shows you a crop of a CFA image. Note that the Bayer pattern (RGGB on this example)
is visible.
Finally, the button Convert, allows, as its name indicates, to start the conversion of files.

Note: The raw images of digital SLRs depend on the manufacturer and are generally closed source formats. Therefore
the decoding of such files is a complex task that must be done by a dedicated code. For Siril, the task of converting
raw files is performed by LibRaw. In fact, if a file format, usually a recent one, does not read, you have to look on the
LibRaw website if it is supported. If it is not, providing them with a raw file can help the dev team to do so. However,
it is also possible that the version of LibRaw embedded in the Siril package is not the most recent version. In this case,
you must either wait for a new release or compile the sources directly.

80 Chapter 7. Preprocessing
 Siril, Release 1.2.0

Fig. 4: Bayer pattern showed on a CFA (Color Filter Array) image.

7.1. Conversion 81
Siril, Release 1.2.0

7.1.1 Correspondence file

After each conversion, a file ending with _conversion.txt is created. It contains the correspondence between the
input images and the images of the sequence obtained during the conversion.

Siril command line

convert basename [-debayer] [-fitseq] [-ser] [-start=index] [-out=]

Converts all images of the current working directory that are in a supported format into Siril's sequence of FITS
images (several files) or a FITS sequence (single file) if -fitseq is provided or a SER sequence (single file) if -ser is
provided. The argument basename is the base name of the new sequence, numbers and the extension will be put
behind it.
For FITS images, Siril will try to make a symbolic link; if not possible, files will be copied. The option -debayer
applies demosaicing to CFA input images; in this case no symbolic link is done.
-start=index sets the starting index number, useful to continue an existing sequence (not used with -fitseq or -ser;
make sure you remove or clear the target .seq if it exists in that case).
The -out= option changes the output directory to the provided argument.

See also CONVERTRAW and LINK

Links: convertraw, link

Siril command line

convertraw basename [-debayer] [-fitseq] [-ser] [-start=index] [-out=]

Same as CONVERT but converts only DSLR RAW files found in the current working directory

Links: convert

7.2 Calibration

Once a sequence is loaded, images can be calibrated, registered and stacked. The calibration is an optional, yet impor-
tant, step and involves bias, dark and flat frames. Calibrating a sequence in Siril can only be done with master bias,
dark and flat frame, which have to be created from their sequences first.

82 Chapter 7. Preprocessing
 Siril, Release 1.2.0

7.2.1 Master files

Fig. 5: Masters settings of the Calibration Tab

Bias

Citing from A Glossary of CCD terminology, to explain what a bias image is:
The bias level of a CCD frame is an artificially induced electronic offset which ensures that the Analogue-to-Digital
Converter (ADC) always receives a positive signal. All CCD data has such an offset which must be removed if the data
values are to be truly representative of the counts recorded per pixel.
To use master-bias in Siril, click on the button to the right of the text entry and browse your files to select the right
master. You can even use master-bias from a library as defined in the preferences.

Tip: The bias frame must be taken with the shutter closed and the shortest possible exposure time. Basically it
corresponds to an exposure of 1/4000s with modern DSLRs.

Synthetic bias

Since the offset signal is very uniform on modern sensors, we recommend processing it as a constant level image. This
has the advantage of saving disk space and minimizing noise in the final image. For this purpose, Siril has a feature
that makes it very easy to do.
During preprocessing of your flats, instead of specifying a masterbias, you can directly type expressions in the folder
selector such as:

=2048

or, if the FITS header contains the OFFSET keyword,

=64*$OFFSET

The = and $ tokens are mandatory. The level must be given in ADU (not float, even if you are working in 32-bit).
Translated into the scripting language, this is written:

preprocess flat -bias="=64*$OFFSET"

The value 2048 is here an example taken for cameras whose master-bias would have a median value of 2048. Generally,
for DSLRs, the value is proportional to a root of 2. In our example, 2048 = 211 .
Fore more details, please refer to the tutorial on the Synthetic biases.

7.2. Calibration 83
Siril, Release 1.2.0

Fig. 6: Example of a bias frame that was shot with a Canon EOS 1100D. Do not rely on the slightly visible bias signal,
the image is auto-stretched and the differences in signal amplitudes are very exaggerated.

84 Chapter 7. Preprocessing
 Siril, Release 1.2.0

Dark

Dark frames contain the thermal noise associated with the sensor, the noise being proportional to temperature and
exposure time. Hence, they should be made at approximately the same temperature as the light frames, this is the
reason why we make dark frames at the end, or in the middle of the imaging session.
To use master-dark in Siril, click on the button to the right of the text entry and browse your files to select the right
master. You can even use master-dark from a library as defined in the preferences.

Tip: Dark frames are made at the same exposure time and ISO/Gain than the subject light frames but with the shutter
closed.

Fig. 7: Example of a dark frame taken with a Canon EOS 1100D with an 300s exposure and at ISO 800.

Fig. 8: An animation showing the removal of the thermal signal thanks to the dark subtraction.

7.2. Calibration 85
Siril, Release 1.2.0

Dark optimization

With the option Optimization, dark subtraction can be optimized so that the noise of the resulting picture (light frame
minus dark frame) is minimized by applying a coefficient to the dark frame. This option is useful when dark frames
have not been taken in optimal conditions.
Here's an example of a situation where the use of this option is necessary. The images were taken with a FLI ProLine
4240 camera. The master-dark used comes from a library and was made with an exposure of 600s. Each subs, on the
other hand, have exposures of 60s. The master-dark has a very distinctive and rather unsightly signal signature: the
presence of 4 preamplifiers in the camera is the cause of such a signal. This defect is obviously also present in the
galaxy image, and calibration of the dark must be meticulously carried out to obtain an image free of all defects.

Fig. 9: This is a light frame and the master-dark of the FLI ProLine 4240 camera. You can see 4 very distinctive bands
caused by the preamplifiers visible on both, lights and master-dark. The images are displayed in histogram equalization
mode, to highlight any defects.

However, in this case, if we use the usual workflow, the calibration result will be very poor. This is because the dark
master was not taken under the same exposure conditions.
The solution is therefore to subtract the bias to the dark, then integrate the bias subtraction with those of the im-
ages, and check the dark optimization box. Siril will automatically calculate a coefficient to be applied to the dark.
Here, it calculates 0.110, which is very coherent, as it corresponds to the 10-fold difference between darks and images
(60/600 = 0.1).

10:34:58: Preprocessing...
10:34:58: Normalisation value auto evaluated: 0.313
10:34:58: 13230 corrected pixels (0 + 13230)
10:34:59: Dark optimization of image 0: k0=0.110
10:34:59: Saving FITS: file pp_M51SDSSr_00002.fit, 1 layer(s), 2048x2048 pixels, 32 bits

86 Chapter 7. Preprocessing
 Siril, Release 1.2.0

Fig. 10: Using the classic workflow, calibration is poor and defects are not corrected. The image is displayed in
histogram equalization mode, to highlight any defects.

Fig. 11: The calibration tab as it should be completed in such a case. Master-flat and master darks have been calibrated
by biases.

7.2. Calibration 87
Siril, Release 1.2.0

Fig. 12: Thanks to dark optimization, calibration is correct. The only residue visible is CCD fringing in the near IR
range, which cannot be removed by calibration. The image is displayed in histogram equalization mode, to highlight
any defects.

88 Chapter 7. Preprocessing
 Siril, Release 1.2.0

Flat

Telescopes generally do not illuminate the detector evenly. In addition, dust on the optical surfaces and the sensor
causes darker patterns in the resulting image, and the sensor itself reacts differently to the number of photons striking
different photosites. To correct for these effects, each bright image must be divided by the master flat, which should be
the median of the single exposures of a homogeneous and unsaturated area.
To use master-flat in Siril, click on the button to the right of the text entry and browse your files to select the right
master. You can even use master-flat from a library as defined in the preferences.

Fig. 13: Example of a flat frame that was shot with a Canon EOS 1100D. The dust present on the optical path, and
especially on the sensor, are clearly visible. The vignetting (darkening of the corners of the image) is also very visible.
The defects are exaggerated by the viewing mode. Also, the grey_flat command was used on this image to get rid of
the Bayer pattern.

CFA equalization

The Equalize CFA option equalizes the mean intensity of RGB layers in a CFA flat image. This is equivalent to apply
the grey_flat command.

Siril command line

grey_flat

Equalizes the mean intensity of RGB layers in the loaded CFA image. This is the same process used on flats during

7.2. Calibration 89
Siril, Release 1.2.0

calibration when the option equalize CFA is used

Auto evaluate normalisation value

If the Auto evaluate normalisation value option is checked, Siril will auto-evaluate the normalisation value. This value
is the mean of the master-flat calibrated with the master-bias. Otherwise, the value indicated in the text box will be
taken into account.

7.2.2 Calibration of light images

The calibration of the light images consists in applying the master bias, dark and flat to the astronomical images in
order to remove the unwanted signal.

Warning: In no case does the calibration reduce the noise of the images. On the contrary, it increases it. This is
why it is important to take as many calibration images as possible, such as darks, in order to minimize the amount
of noise in the images.

Fix X-Trans AF artifact

This Fix X-Trans AF artifact option helps to fix the Fujifilm X-Trans Auto Focus pixels. Indeed, because of the phase
detection auto focus system, the photosites used for auto focus get a little less light than the surrounding photosites.
The camera compensates for this and increases the values from these specific photosites giving a visible square in the
middle of the dark/bias frames. This option has no effect on Bayer pattern. The option is only enabled if a master-bias
or master-dark is loaded and used.

Fig. 14: X-Trans artifact fixed by the algorithm of Siril

90 Chapter 7. Preprocessing
 Siril, Release 1.2.0

Cosmetic Correction

Cosmetic correction is the technique used to correct defective pixels in images. Indeed, any camera sensor has photo-
sites that do not react correctly to photon reception. This is visible in the image with pixels with values very different
from those of their nearest neighbors. These pixels are called hot pixels, if the value is much higher, or cold pixels
when it is much lower. Siril offers two algorithms to correct these defective pixels if the option Enable Cosmectic
Correction is checked.

Using Master-Dark

This method requires the presence of a master-dark. Siril will search for pixels whose deviation from the median
exceeds x times the standard deviation 𝜎. This value is adjustable for both hot and cold pixels.

It is possible to estimate the number of pixels that will be corrected in the calibrated image by pressing the Estimate
button. If the corrected pixel value is displayed in red, it means that this number exceeds 1% of the total number of pixels
in the image. In this case you should increase the value of the coefficient, or uncheck the corresponding correction. If
the images are from a color sensor then it is necessary to check the CFA option.

Using Bad Pixel Map

The other method uses a file that contains the coordinates of the defective pixels. This file is a simple text file and can
initially be created with the command find_hot.

P 325 2855 H
P 825 2855 C
P 838 2855 H
P 2110 2855 H
P 2702 2855 H
P 424 2854 H

7.2. Calibration 91
Siril, Release 1.2.0

Siril command line

find_hot filename cold_sigma hot_sigma

Saves a list file filename (text format) in the working directory which contains the coordinates of the pixels which
have an intensity hot_sigma times higher and cold_sigma lower than standard deviation, extracted from the loaded
image. We generally use this command on a master-dark file. The COSME command can apply this list of bad pixels
to a loaded image, see also SEQCOSME to apply it to a sequence

Links: cosme, seqcosme

Lines P x y type will fix the pixel at coordinates (x, y) type is an optional character (C or H) specifying to Siril if
the current pixel is cold or hot. This line is created by the command FIND_HOT but you also can add some lines
manually:
Lines C x 0 type will fix the bad column at coordinates x.
Lines L y 0 type will fix the bad line at coordinates y.

This file, which can be edited by hand, is to be loaded as a Bad Pixel Map.

Finally, if the images are from a color sensor then it is necessary to check the CFA option.

92 Chapter 7. Preprocessing
 Siril, Release 1.2.0

Output sequence

This section groups the options that can be applied to the output.

• The Output Prefix entry box adds a prefix to the output images, to easily identify them. By default, the prefix is
pp_, which means pre-processed.
• The drop-down list defines the type of destination sequence.
– FITS images: one FITS file per image.
– SER sequence: one SER file for the whole sequence (limited to 16 bits per channel).
– Sequence FITS: one FITS file for the entire sequence.
• Last option, Debayer before saving. Check this option if you want to apply a demosaicing algorithm to your
frames right after they were calibrated. By doing this, you skip one manual step which can take some time.

Command lines

Siril command line

preprocess sequencename [-bias=filename] [-dark=filename] [-flat=filename] [-cc=dark␣

˓→[siglo sighi] || -cc=bpm bpmfile] [-cfa] [-debayer] [-fix_xtrans] [-equalize_cfa] [-

˓→opt] [-all] [-prefix=] [-fitseq]

Calibrates the sequence sequencename using bias, dark and flat given in argument.

For bias, a uniform level can be specified instead of an image, by entering a quoted expression starting with an = sign,
such as -bias="=256" or -bias="=64*$OFFSET".

By default, cosmetic correction is not activated. If you wish to apply some, you will need to specify it with -cc=
option.
You can use -cc=dark to detect hot and cold pixels from the masterdark (a masterdark must be given with the -dark=
option), optionally followed by siglo and sighi for cold and hot pixels respectively. A value of 0 deactivates the
correction. If sigmas are not provided, only hot pixels detection with a sigma of 3 will be applied.
Alternatively, you can use -cc=bpm followed by the path to your Bad Pixel Map to specify which pixels must be
corrected. An example file can be obtained with a find_hot command on a masterdark.

Three options apply to color images (in CFA format): -cfa for cosmetic correction purposes, -debayer to demosaic
images before saving them, and -equalize_cfa to equalize the mean intensity of RGB layers of the master flat, to avoid
tinting the calibrated image.
The -fix_xtrans option is dedicated to X-Trans images by applying a correction on darks and biases to remove a
rectangle pattern caused by autofocus.

7.2. Calibration 93
Siril, Release 1.2.0

It is also possible to optimize the dark subtraction with -opt, which requires both bias and dark masters to be provided.
By default, frames marked as excluded will not be processed. The argument -all can be used to force processing of all
frames even if marked as excluded.
The output sequence name starts with the prefix "pp_" unless otherwise specified with option -prefix=.
If -fitseq is provided, the output sequence will be a FITS sequence (single file)

Siril command line

preprocess_single imagename [-bias=filename] [-dark=filename] [-flat=filename] [-cfa] [-

˓→debayer] [-fix_xtrans] [-equalize_cfa] [-opt] [-prefix=]

Calibrates the image imagename using bias, dark and flat given in argument.

For bias, a uniform level can be specified instead of an image, by entering a quoted expression starting with an = sign,
such as -bias="=256" or -bias="=64*$OFFSET".

By default, cosmetic correction is not activated. If you wish to apply some, you will need to specify it with -cc=
option.
You can use -cc=dark to detect hot and cold pixels from the masterdark (a masterdark must be given with the -dark=
option), optionally followed by siglo and sighi for cold and hot pixels respectively. A value of 0 deactivates the
correction. If sigmas are not provided, only hot pixels detection with a sigma of 3 will be applied.
Alternatively, you can use -cc=bpm followed by the path to your Bad Pixel Map to specify which pixels must be
corrected. An example file can be obtained with a find_hot command on a masterdark.

Three options apply to color images (in CFA format): -cfa for cosmetic correction purposes, -debayer to demosaic
images before saving them, and -equalize_cfa to equalize the mean intensity of RGB layers of the master flat, to avoid
tinting the calibrated image.
The -fix_xtrans option is dedicated to X-Trans images by applying a correction on darks and biases to remove a
rectangle pattern caused by autofocus.
It is also possible to optimize the dark subtraction with -opt, which requires both bias and dark masters to be provided.
The output filename starts with the prefix "pp_" unless otherwise specified with option -prefix=

7.2.3 Understanding how the flats correct the lights

The point of this section is to give a bit more insight in how the different levels play a role in the correction of the lights
by the flats.
We will disregard here any considerations about noise (again, noise does not vanish with masters subtraction or division,
it decreases by averaging over many realizations of the same random process). We also disregard particular spatial
patterns such as ampglow or dust.
If we try to quantify the intensity of background pixels in the different frames we have, we can write the following

94 Chapter 7. Preprocessing
 Siril, Release 1.2.0

expressions:
(︂ )︂2
𝑊
𝐿=𝑎−𝑏× 𝑥− + 𝑑rate × 𝑡lights + 𝑜 (7.1)
2
𝐷 = 𝑑rate × 𝑡lights(7.2)
+𝑜
(︃ (︂ )︂2 )︃
𝑊
𝐹 =𝐾 𝑎−𝑏× 𝑥− (7.3)
+𝑜
2
𝑂(7.4)
=𝑜

with, 𝐿 for Lights, 𝐷 for Darks, 𝐹 for Flats and 𝑂 for Bias.

2 ) . We have chosen here a quadratic

For the lights 𝐿, the first part is a spatial illumination component, i.e., 𝑎 − 𝑏(𝑥 − 𝑊 2

variation with a maximum value 𝑎 in the middle of the frame of width 𝑊 , even about the center of the sensor. This is not
the exact spatial shape of vignetting but it is a good enough approximation to understand how it works. In addition to this
spatial illumination term, there is a term varying with exposure time which is usually named dark current (𝑑rate × 𝑡lights )
but which does not depend on the position of the pixel on the sensor. And finally there is a pedestal, i.e. the offset.
This offset is present in any frame which is shot, so that we find it in all the expressions.
The darks 𝐷 not being illuminated, they only bear the dark current term, with same intensity as lights as they are shot
for the same amount of time, and the offset term.
The flats 𝐹 also have a spatial term, proportional to the term found in the lights. The factor 𝐾, larger than 1, simply
shows that their intensity is larger. To write this, we only need to assume that the pixels respond linearly to the number
of photons they gather, which is sensible. We could also have written a dark current term, proportional to the exposure
time of flats. But unless this time is significant, we can assume it is negligible. If it is not the case, then it means you
need to shoot dark flats, or at least to assess their level.
And finally the offsets 𝑂 only measure the offset level.
To visualize these levels, we have plotted here-below these expressions as curves wrt. position on a frame and we
encourage you to do the same and to play around with the inputs.
• 𝑎 = 200[ADU]
• 𝑏 = 0.0003[ADU/px2 ]
• 𝑑rate = 1[ADU/s]
• 𝑡lights = 10[s]
• 𝑜 = 2048[ADU]
• 𝑊 = 1000[px]
𝐿, 𝐷 and 𝑂 values in ADU are given on the left scale while 𝐹 are on the scale reported to the right.
Now what does calibrating your lights mean? When you calibrate your lights, you perform the following operation:
𝐿−𝐷
𝐿𝑐 = .
𝐹 −𝑂
The term 𝐹 − 𝑂 is a flat from which you have subtracted the offset level (whether it is a masterbias or simply a level).
This is the operation performed prior to stacking your masterflat. And the term 𝐿 − 𝐷 represents a light from which
you have subtracted the dark current level and the offset, i.e. a masterdark. If you replace with the expressions shown
above, you end up with the following:
1
𝐿𝑐 = .
𝐾
No spatial variation term is left, you have flat-fielded your lights! Getting a sensible value in ADU (and not 1/𝐾) is
what Siril does when you check Auto evaluate normalisation value in the Calibration tab.

7.2. Calibration 95
Siril, Release 1.2.0

96 Chapter 7. Preprocessing
 Siril, Release 1.2.0

And you can try with any other combination, no other will get rid of spatial variations.
Just to illustrate this, We have plotted below the result of different combinations. To put everything on the same scale,
all the results are normalized to have the same intensity of 1 in the middle of the frame. The following tests are shown:
• 𝐿 − 𝐷 : you have just shot darks.
• 𝐿/𝐹 : you have just shot flats.
• 𝐿/(𝐹 − 𝑂) : you have shot flats and corrected them by an offset (either a master or a synthetic one).
• (𝐿 − 𝑂)/(𝐹 − 𝑂) : you have just flats corrected by offset. But you have subtracted the offset from your lights
as well.
• (𝐿 − 𝐷)/𝐹 : you have shot flats and darks but no offsets.
• (𝐿 − 𝐷)/(𝐹 − 𝑂) : you have done everything by the book.

Interestingly, you can notice that:

• 𝐿 − 𝐷 shows obviously no correction for vignetting.
• Both 𝐿/𝐹 and 𝐿/(𝐹 − 𝑂) show overcorrection or inverse vignetting.
• Getting very close to the optimal result, (𝐿 − 𝐷)/𝐹 and (𝐿 − 𝑂)/(𝐹 − 𝑂) shows a field almost flat. This, of
course, will depend how much your sensor has dark current and how much vignetting your optical train shows.
• The reference calibration gives a flat field.
The conclusions that you can draw from the above are:

7.2. Calibration 97
Siril, Release 1.2.0

• You are better off correcting your lights with offset (masterbias or simply a level) if you have not shot darks.
• Even better, if you don't have time to shoot a series of darks, it is probably worth shooting at least one dark,
measure its median, and subtract this (synthetic) dark from your lights. It will of course not correct for ampglow
or enable hot pixel correction, but your lights will at least be flat!

Now what about dust...?

In order for your flats to also correct for these nasty spots, the sad news is you also need to get all the calibration frames
in the equation. We have added a small local ADU deficit in the lights and flats to illustrate this effect.

As you can see, only the combination (𝐿 − 𝐷)/(𝐹 − 𝑂) can get rid of it.
To further illustrate the equations and curves above, nothing is better than a real-life example. All pictures below are
shown courtesy of G. Attard.

98 Chapter 7. Preprocessing
 Siril, Release 1.2.0

7.2. Calibration 99
Siril, Release 1.2.0

Fig. 15: 𝐿 − 𝐷

100 Chapter 7. Preprocessing

 Siril, Release 1.2.0

Fig. 16: 𝐿/𝐹

7.2. Calibration 101

Siril, Release 1.2.0

Fig. 17: 𝐿/(𝐹 − 𝑂)

102 Chapter 7. Preprocessing

 Siril, Release 1.2.0

Fig. 18: (𝐿 − 𝑂)/(𝐹 − 𝑂)

7.2. Calibration 103

Siril, Release 1.2.0

Fig. 19: (𝐿 − 𝐷)/(𝐹 − 𝑂)

104 Chapter 7. Preprocessing

 Siril, Release 1.2.0

7.2.4 Troubleshooting calibration

Calibration is a very simple step arithmetically, and cannot fail if the input data conforms to what is expected for
astronomical images.
However, users are regularly confronted with situations where the calibrated images are not correct. In this section,
we'll give you an overview of the problems encountered and how to avoid them.
First of all, the statistic tool is an invaluable aid to understanding problems, and is used in the majority of cases to fix
issues.
• When analyzing the statistics of a master-dark, it must first be black. This is because these images are taken with
the cap closed, and there's no reason why one of the photosites should be privileged. The image must look as if
it had been taken by a monochrome sensor, with the Bayer matrix not visible. Below, here's an example where
the master-dark has undergone an unwanted color balance for this type of image. As a result, it is no longer black
and the Bayer pattern is visible. Such a dark is unfit for use and must be remade.
• During the night session, it's very important to set the OFFSET value to the same value for all images. Particularly
it is mandatory to have the same setting for the pairs darks/lights and bias/flats. Failing to meet the first condition
may end up in losing significant data (clipping pixels to the left hand side of the histogrram). Failing to meet
both conditions will most probably prevent your images to be correctly flat-fielded (see section above).
• Check darks and lights levels: the median value of lights images must be sufficiently higher than that of darks to
avoid generating images full of pixels with negative values.
• If you have used the same settings for darks and biases, their median values should be very close to each other
(at least with a cooled camera). Otherwise, it may mean you have you have a light leakage that has affected your
darks (biases are less senstive as they are exposed for a much shorter time). So always inspect your master-dark
to see whether there's a gradient or a brighter patch in the center. This is not to be confused with ampglow which
is normal for certain cameras.
• We strongly recommend that you shoot your images in the same way: same software / same computer or astrobox
/same image format. In fact, each program may use its own writing conventions, and images may no longer be
compatible with each other. We often hear of users making all their images with an astrobox, and making the
flats the next day directly with their DSLR. In this case, the images are often of different sizes, making calibration
impossible.
• An error often encountered when running a script is the presence of JPG images in one of the input folders
(darks/biases/flats/lights), most times snapshots saved by the acquisition software for faster browsing. The con-
sequence of this kind of error is that calibration fails and stops, complaining that the images are not of the same
size. In fact, since JPG images are already demosaiced, they have three channels, while RAW images have only
one. Remove all JPG images from the input folders to fix this issue.
• Check that the flat is not overexposed. Flat frames are used to correct for pixel-to-pixel sensitivity variations in
the sensor. If some pixels are overexposed, their true sensitivity may not be accurately represented, leading to
incorrect corrections during the calibration process. An overexposed flat is the guarantee of a failed calibration.
To check for overexposed pixels, you can load a flat subframe and use the Image Processing → Histogram
Transformation... to show the histogram of the image. The snapshot below shows that one of the peaks is clipped
to the right. As a prudent approach, you should always check that the right tail of the peak furthest to the right is
not above 80%, to avoid going in a zone where your sensor may become non-linear.

7.2. Calibration 105

Siril, Release 1.2.0

Fig. 20: A close look at the statistics shows that the median value of each channel is different, whereas they should be
identical (or almost). Also, Bayer's pattern is clearly visible.

106 Chapter 7. Preprocessing

 Siril, Release 1.2.0

Fig. 21: White-clipping of a flat. When this happens, it means you should lower the gain or the exposure time.

7.3 Registration

Registration is basically the process of aligning the images from a sequence to be able to process them afterwards. All
the processes described hereafter calculate the transformation to be applied to each image in order to be aligned with
the reference image of the sequence.
Siril's strength lies in the wide variety of recording algorithms offered. Each method is explained below. Pressing the
Go register button starts the registration of the sequence.
It is possible to choose the registration channel. Green is the default for color images, Luminance for monochrome.
The (*) sign appearing after the channel's name means that registration data is already available for this layer. When
processing images, registration data is taken from the default layer if available (for RGB images: Green, else fallback
to Blue then Red).

7.3.1 Theory

Registration process

What we call Registration is in fact a three-step process:

1. Detect features to be matched in all the images
2. Compute the transformations between each image and the reference image
3. Apply the computed transformation to each image to obtain new images
Depending on the registration method selected, the 3 steps occur (or not) into a single process. Siril uses the most
sensible defaults (choosing whether or not to apply the computed transformation) depending on the registration method
selected, but understanding the internal machinery may help you to change this behavior to better suit your needs.

7.3. Registration 107

Siril, Release 1.2.0

Algorithms

The table here below details the different algorithms used for the first 2 steps (detection and transformation calculation).

Registra- Feature detec- Transformation calculation Shift Eu- Sim- Affine Ho-
tion method tion clidean ilar- mog-
ity raphy
Global Dynamic PSF Triangles matching + RANSAC subpixel x x x
2 pass subpixel x x x
1-2-3 stars PSF minimization Singular Value Decomposition subpixel (2-3
in selection box (2-3 stars) Difference (1 star) (1 star) stars)
Image cross correlation on selection box pixel
Pattern
alignment
KOMBAT Max of convolution in spatial domain on selection pixel
box
Comet PSF minimization Shifts from velocity vector us- subpixel
in selection box ing timestamps
Manual Your eyes Your hand pixel

It is also important to keep in mind how the registered sequence is fed into the stacking process that is generally used
right after registration:
• if the transformation consists only of pixel-wise shifts, the stacking algorithm can use these shifts on-the-fly
when reading the images. It means you do not need to generate "registered images". This saves storage space
and skips interpolation. It is, of course, at the expense of less accurate registration (i.e. subpixel accuracy) but
is generally used on planetary/lucky imaging images where sampling is small. This can also be applied with
a registration method which computes subpixel shifts. During the stacking process, the shifts will be rounded
off to pixel precision. In any other case, meaning the stacking is fed with a sequence where the registration has
computed transformations more complex than just shifts but the registered images have not been saved, Siril will
emit a warning inviting you to export the registered images before proceeding to stacking.
• In all other cases, once the transformations have been computed, the transformed images need to be saved before
proceeding to stacking, generally named with r_ prefix.

Image transformations

Siril uses linear transformations, with different degrees-of-freedoms, to map an image to the reference image:
• Shift is a 2 degree-of-freedom (x/y shifts) rigid mapping, well-suited for images with no distortion, no scaling
and no field rotation. It needs only 1 pair of stars (or feature) to be matched to define the transformation.
• Euclidean is a 3 degree-of-freedom (x/y shifts + one rotation) rigid mapping, for images with no distortion, no
scaling. It needs at least 2 pairs of stars to be matched to define the transformation.
• Similarity is a 4 degree-of-freedom (one scale, one rotation and x/y shifts) more rigid mapping than homog-
raphy, well-suited for images with no distortion. It needs at least 2 pairs of stars to be matched to define the
transformation.
• Affine is a 6 degree-of-freedom (two scales, one shear, one rotation and x/y shifts) more rigid mapping than
homography, well-suited for images with little distortion. It needs at least 3 pairs of stars to be matched to define
the transformation.
• Homography is the default transformation which uses an 8-degree-of-freedom transform to warp the images onto
the reference frame. This is well-suited for the general case and strongly recommended for wide-field images. It

108 Chapter 7. Preprocessing

 Siril, Release 1.2.0

needs at least 4 pairs of stars to be matched to define the transformation.

Reference image

This is the image which is used as a common reference to compute the transformations that send all the images of the
sequence onto this particular one.
If not set manually, the reference image is chosen with the following criteria:
• if the sequence has already been registered, it is the best image, in term of lowest FWHM or highest quality
depending on the type of registration
• Otherwise, it is the first image of the sequence that is not excluded.
To specify an image as the reference, you can:
• Open the Frame selector, select the image to be set as the new reference and click the button Reference Image.
• Use the command setref . For instance, if you want to set image #10 as the reference:

7.3. Registration 109

Siril, Release 1.2.0

setref 10

Siril command line

setref sequencename image_number

Sets the reference image of the sequence given in first argument. image_number is the sequential number of the
image in the sequence, not the number in the filename, starting at 1

Fig. 22: The frame list dialog. You can browse all images in the sequence.

During stacking, the reference image is used as the normalization reference as well, if normalization is activated.

7.3.2 Registration methods

Global registration

This is probably the more powerful and accurate algorithm to align deep-sky images.
The global matching is based on triangle similarity method for automatically identify common stars in each image
[Valdes1995]. Our implementation is based upon the program match from Michael Richmond. Then, RANSAC
[Fischler1981] algorithm is used on the star lists to further reject outliers and determine the projection matrix. The
robustness of the algorithm depends on the ability to detect the stars while avoiding false detections. Siril has a very

110 Chapter 7. Preprocessing

 Siril, Release 1.2.0

elaborate star detection algorithm that avoids as much as possible to select objects that are not stars in the fastest possi-
ble time. The detection of the brightest stars is usually the most important. However, if there is a need to detect fainter
stars, then the Dynamic PSF window can be used to adjust the detection parameters.

Fig. 23: Automatic detection of stars in a single frame

There are few options associated with this alignment method because it is fairly automatic.
The Transformation dropdown menu allows to choose between different transformations.

Warning: The initial star matching uses triangle similarity algorithm, in consequence the minimum of star pairs
must be at least of 3 for Shift, Similarity and Affine and of 4 for Homography.

Other options are:

• The Minimum Star Pairs button sets the minimum number of star pairs a given frame can have in relation with
the reference frame. If a given light frame has less star pairs, it will not be registered. To the right of this option
is a button that opens the PSF Dynamique tool.
• The option Maximum Stars Fitted defines the maximum number of stars to be searched for in each frame (default
2000). The larger this value, the more stars will potentially be detected, resulting in a longer detection but more
accurate registration.
• Finally, the last option, Match stars in selection, if you want to perform the Global Star Alignment algorithm

7.3. Registration 111

Siril, Release 1.2.0

within the selected area in the reference image. If no selection are done, this option is ignored.

Siril command line

register sequencename [-2pass] [-noout] [-drizzle] [-prefix=] [-minpairs=] [-transf=] [-

˓→layer=] [-maxstars=] [-nostarlist] [-interp=] [-noclamp] [-selected]

Finds and optionally performs geometric transforms on images of the sequence given in argument so that they may be
superimposed on the reference image. Using stars for registration, this algorithm only works with deep sky images.
Star detection options can be changed using SETFINDSTAR or the Dynamic PSF dialog. The detection is done on
the green layer for colour images, unless specified by the -layer= option with an argument ranging from 0 to 2 for red
to blue.

The -2pass and -noout options will only compute the transforms but not generate the transformed images, -2pass
adds a preliminary pass to the algorithm to find a good reference image before computing the transforms, based on
image quality and framing. To generate transformed images after this pass, use SEQAPPLYREG. -nostarlist disables
saving the star lists to disk.

The option -transf= specifies the use of either shift, similarity, affine or homography (default) transformations
respectively.
The option -drizzle activates the sub-pixel stacking by up-scaling by 2 the generated images.
The option -minpairs= will specify the minimum number of star pairs a frame must have with the reference frame,
otherwise the frame will be dropped and excluded from the sequence.
The option -maxstars= will specify the maximum number of star to find within each frame (must be between 100 and
2000). With more stars, a more accurate registration can be computed, but will take more time to run.

The pixel interpolation method can be specified with the -interp= argument followed by one of the methods in the list
no[ne], ne[arest], cu[bic], la[nczos4], li[near], ar[ea]}. If none is passed, the transformation is forced to shift and a
pixel-wise shift is applied to each image without any interpolation.

112 Chapter 7. Preprocessing

 Siril, Release 1.2.0

Clamping of the bicubic and lanczos4 interpolation methods is the default, to avoid artefacts, but can be disabled with
the -noclamp argument.

All images of the sequence will be registered unless the option -selected is passed, in that case the excluded images
will not be processed

If created, the output sequence name starts with the prefix "r_" unless otherwise specified with -prefix= option

Links: setfindstar, psf , seqapplyreg

2pass registration

The global star alignment is done in two passes, allowing the reference frame to be chosen from detected star information
instead of automatically choosing the first frame of the sequence. The proposed options are similar to the Global
Registation algorithm but this method does not create any sequences and all alignment information is saved in the seq
file.
During star detection, Siril sets a maximum of 2000 stars to be found (this can also be changed with the appropriate
option). In case more than one image has reached the maximum star limits, the star lists of all images are screened
again. A new minimum detection threshold is defined to be able sort the images by both number of stars detected and
FWHM.
Unless specified otherwise, the star lists of all images are saved when using this method, the .fit(s) extension being
replaced by .lst. This allows to re-run the 2pass algorithm very quickly with different parameters, say different
transformation. In case the star detection have been modified, the process detects these changes and re-run the analysis
as required.
This registration must generally followed by Apply Existing Registation in order to apply the transformation and build
a new sequence, unless you have chosen to compute Shift.
These lines perform a 2pass registration on a sequence named pp_light and applies it. The output is a sequence pp_light.

# Align lights in 2 passes

register pp_light -2pass
seqapplyreg pp_light

These lines perform a 2pass registration on a sequence named colors and applies it while cropping the output images
to the minimum coommon area. The output is a sequence pp_colors. This can be useful before compositing mono
images (the areas which are not common to all images are cropped).

# Align layers in 2 passes and crop away borders

register colors -2pass
seqapplyreg colors -framing=min

7.3. Registration 113

Siril, Release 1.2.0

1-2-3 stars registration

When the images contain few stars, for example in the case of DSO Lucky Imaging images where the frame exposure
is less than one second. It is possible that the global registration algorithm fails, even if you change the detection
parameters in the Dynamic PSF window. It may then be interesting to make a manual detection of the stars you want
to align. This is the interest of the 1, 2 or 3 star registration algorithm.

The principle of this method is to draw a selection area around a star and click on the Pick 1st star button, then so on.
• If only one star is selected, only the translation between the images will be calculated. Therefore the Shift only
button is automatically selected. The shift values are then storred in the seq file.
• If two or three stars are selected, then the rotation can be calculated and applied to create a new sequence.
However, if the Shift only option is selected, which is not mandatory, only the shifts will be calculated.
The option Follow star movement use the position of the star(s) found in the previous image as new centre for the current
image registration. This allows the selection area to be smaller, registration faster, and accounts for drift or images with
a large number of stars.

Warning: Enabling this option requires the registration to not be parallelized, it will run on one CPU core only.

Image Pattern alignment (planetary-full disk)

This is a simple registration by translation method using cross correlation in the spatial domain.
This method is fast and is used to register planetary movies, in which constrasted information can be seen on large
areas of the image. It can also be used for some deep-sky images registration. Nevertheless keep in mind that it is
a single point alignment method, which makes it poorly suited for high definition planetary alignment. But, it does
effectively anchor the images to stabilize the sequence. Simply draw a selection around the object (the planet for
example) and make sure that its movement during the sequence is contained within the selection. Only the translation
can be calculated with this method.

114 Chapter 7. Preprocessing

 Siril, Release 1.2.0

7.3. Registration 115

Siril, Release 1.2.0

KOMBAT

This method comes from the OpenCV library, a library widely used in Siril. They explain:
It simply slides the template image over the input image (as in 2D convolution) and compares the template and patch
of input image under the template image. Several comparison methods are implemented in OpenCV. (You can check
docs for more details). It returns a grayscale image, where each pixel denotes how much does the neighbourhood of
that pixel match with template.
In practice, simply draw a selection around the object (the planet for example) and make sure that its movement during
the sequence is contained within the selection. Only the translation can be calculated with this method.

Comet/Asteroid registration

The cometary registration tool works in a very simple way, in two steps.
1. With the frame selector, select the first image of the sequence, surround the comet nucleus, then click on the
button Pick object in #1.
2. Then select the last image of the sequence, surround the nucleus of the comet, then click on the button Pick object
in #2.
The comet velocity ∆𝑥 and ∆𝑦 is computed in pixel per hour if everything is ok.

Warning: The alignment of the comet must be done on images whose stars have been previously aligned. Either
via a new sequence, with the global alignment, or by having saved the registration information in the seq file. In
this last case, the option Accumulate reg. data (explained below) makes sense.

Note: To fully function, the images must have a timestamp. Only FITS, SER and TIFF images are compatible with
this feature.

116 Chapter 7. Preprocessing

 Siril, Release 1.2.0

Manual Registration

This last method of registration is very particular, which explains its separate position, and allows to align images
manually. Of course, only the translation between images is allowed.
The first thing to do is to define two previews in the image. Clicking on the button Set first preview will initialize the
first preview. You then need to click on an area of the image, ideally a star in the vicinity of an edge of the image to set
the preview area. A click on the second button Set second preview allows to do the same on a second point.

It is very important to have a reference image already set with the Frame selector. By default, it is the first image. The
user is free to choose the one he wants. It will be used as a reference layer, seen by transparency, to align the images
manually with the numerical buttons. Then, browse the image one by one to apply the same method to the whole
sequence.

7.3. Registration 117

Siril, Release 1.2.0

Fig. 24: The Y-shift is too large, same stars on different frames do not overlap.

118 Chapter 7. Preprocessing

 Siril, Release 1.2.0

Fig. 25: X- and Y-shift look fine. The current image is aligned to the reference one.

7.3. Registration 119

Siril, Release 1.2.0

Apply Existing registration

This is not an algorithm but rather a commodity to apply previously computed registration data stored in the sequence
file. The interpolation method and simplified drizzle can be selected in the Output Registration section. You can also
use image filtering to avoid saving unnecessary images, as in stacking Image rejection.
Four framing methods are available:

• : current uses the current reference image. This is the default behavior.

• : maximum (bounding box) adds a black border around each image as required so that no
part of the image is cropped when registered.

• : minimum (common area) crops each image to the area it has in common with all images
of the sequence.

• : center of gravity determines the best framing position as the center of gravity (cog) of
all the images.

Siril command line

seqapplyreg sequencename [-drizzle] [-interp=] [-noclamp] [-layer=] [-framing=] [-

˓→prefix=] [-filter-fwhm=value[%|k]] [-filter-wfwhm=value[%|k]] [-filter-round=value[

˓→%|k]] [-filter-bkg=value[%|k]] [-filter-nbstars=value[%|k]] [-filter-quality=value[

˓→%|k]] [-filter-incl[uded]]

Applies geometric transforms on images of the sequence given in argument so that they may be superimposed on the
reference image, using registration data previously computed (see REGISTER).

120 Chapter 7. Preprocessing

 Siril, Release 1.2.0

The output sequence name starts with the prefix "r_" unless otherwise specified with -prefix= option.

The option -drizzle activates up-scaling by 2 the images created in the transformed sequence.

The pixel interpolation method can be specified with the -interp= argument followed by one of the methods in the list
no[ne], ne[arest], cu[bic], la[nczos4], li[near], ar[ea]}. If none is passed, the transformation is forced to shift and a
pixel-wise shift is applied to each image without any interpolation.
Clamping of the bicubic and lanczos4 interpolation methods is the default, to avoid artefacts, but can be disabled with
the -noclamp argument.

The registration is done on the first layer for which data exists for RGB images unless specified by -layer= option (0, 1
or 2 for R, G and B respectively).

Automatic framing of the output sequence can be specified using -framing= keyword followed by one of the methods
in the list { current | min | max | cog } :
-framing=max (bounding box) adds a black border around each image as required so that no part of the image is
cropped when registered.
-framing=min (common area) crops each image to the area it has in common with all images of the sequence.
-framing=cog determines the best framing position as the center of gravity (cog) of all the images.

Filtering out images:

Images to be registered can be selected based on some filters, like those selected or with best FWHM, with some of
the -filter-* options.

Links: register

With filtering being some of these in no particular order or number:

7.3. Registration 121

Siril, Release 1.2.0

[-filter-fwhm=value[%|k]] [-filter-wfwhm=value[%|k]] [-filter-round=value[%|k]] [-filter-

˓→bkg=value[%|k]]

[-filter-nbstars=value[%|k]] [-filter-quality=value[%|k]] [-filter-incl[uded]]

Best images from the sequence can be stacked by using the filtering arguments. Each of these arguments can remove
bad images based on a property their name contains, taken from the registration data, with either of the three types of
argument values:
- a numeric value for the worse image to keep depending on the type of data used (between 0 and 1 for roundness and
quality, absolute values otherwise),
- a percentage of best images to keep if the number is followed by a % sign,
- or a k value for the k.sigma of the worse image to keep if the number is followed by a k sign.
It is also possible to use manually selected images, either previously from the GUI or with the select or unselect
commands, using the -filter-included argument.

7.3.3 Output Registration

This frame contains all the output elements for the sequence.

• The button Simplified Drizzle x2 activates the simplified drizzle algorithm for the processing of this sequence.
An up-scale (x2) will be applied to the registered frame or during stacking depending on which registration is
chosen, that will result in higher resolution images. This option is adapted for under-sampled images, i.e, when
the telescope focal length is too short for the pixel size. One may consider that the system is under-sampled when
FWHM is smaller than 2 pixels. The correct name of this method should be super-resolution stacking, but for a
more convenient understanding we called it Simplified Drizzle x2.

Warning: The counterpart of this technic is that the amount of memory and disk space needed to create
and process drizzled images is multiplied by the square of the Drizzle factor.

122 Chapter 7. Preprocessing

 Siril, Release 1.2.0

• When button Save transformation in seq file only is checked, the transformed images are not saved as a newly
registered sequence. In both cases, the transformation matrices are saved to the sequence file. The registration
data can then be inspected and some images unselected, prior to applying the transformations using the Apply
Existing Registration method. This option is automatically checked for alignment method that produce shift only
registration data. If this option is unchecked, then it is possible to define a prefix for the new sequence that will
be created. By default it is r_.
• If a new sequence is created, with the application of a complete transformation, then the pixels of the result-
ing images are interpolated by an algorithm that is left to the user's choice. There are 5 possible interpolation
algorithms, plus a None option:
– Nearest Neighbor
– Bilinear
– Bicubic
– Pixel Area Relation
– Lanczos-4
– None
The most efficient interpolation methods are generally bicubic and Lanczoz (used by default). However, they
usually require the Clamping interpolation option to be enabled to avoid ring artifacts around the stars. But the
latter may be useless in some cases. We recommend you to test with your images.
The special case of None is reserved for the case of global registration and Apply Existing registration. If you
want to export or save a sequence that contains only translation, without using interpolation (so as not to modify
the pixel values), you should select None.
• Last option Accumulate reg. data, must be checked if you want the new registration data to be added to the
previous one. This option is useful when sequence has previously been aligned using a method that does not
build a new sequence, but it should be unchecked when the comet/asteroid algorithm is applied several times.

7.3.4 References

7.4 Stacking

The final preprocessing step to do with Siril is to stack the images. Image stacking is a technique used in astropho-
tography to increase the quality and detail of an image by combining multiple photographs into a single, composite
image. The process involves taking multiple images of the same object and then align and average the frames together
to reduce the noise and increase the signal-to-noise ratio. This results in a final image that has less noise, greater detail
and greater dynamic range than a single exposure.

7.4.1 Stacking methods

Sum stacking

This is the simplest

√ algorithm: each pixel in the stack is summed. The increase in signal-to-noise ratio (SNR) is
proportional to 𝑁 , where 𝑁 is the number of images. Because of the lack of normalisation and rejection, this
method should only be used for planetary processing.
For 8 or 16 bit per channel input images, the sum is done in a 64 bit integer before being normalized to the maximum
pixel value and saved as a 16 bit unsigned integer or 32 bit floating point image.

7.4. Stacking 123

Siril, Release 1.2.0

This stacking method should be used for 8-bit input images because it will increase the dynamic of the images while
stacking them, making features discernable. Stacking with an mean or median method such a sequence would only
decrease the noise but not improve the dynamic of the image, the result would still be 8 bits deep.

Average Stacking With Rejection

This method of stacking computes a mean of the pixels in a stack after having excluded deviant pixels and an optional
normalisation
√ of the images against the reference image. As for sum stacking, the improvement in SNR is proportional
to 𝑁 . There are several ways to normalize the images and several ways to detect and replace or exclude deviant
pixels, explained below.

Warning: Some operating systems limit the number of images that can be opened at the same time, which is
required for median or mean stacking methods. For Windows, the limit is 2048 images. If you have a lot of images,
you should use another type of sequence, described here.

Rejection methods

• Percentile Clipping: This is a one step rejection algorithm ideal for small sets of data (up to 6 images).
• Sigma Clipping: This is an iterative algorithm which will reject pixels whose distance from median will be
farthest than two given values in sigma units(𝜎 low, 𝜎 high).
• MAD Clipping: This is an iterative algorithm working as Sigma Clipping except that the estimator used is the
Median Absolute Deviation (MAD). This is generally used for noisy infrared image processing.
• Median Sigma Clipping: This is the same algorithm as Sigma Clipping except than the rejected pixels are
replaced by the median value of the stack.
• Winsorized Sigma Clipping: This is very similar to Sigma Clipping method, except it is supposed to be more
robust for outliers detection, see Huber's work [Peter2009].
• Generalized Extreme Studentized Deviate Test [Rosner1983]: This is a generalization of Grubbs Test that is
used to detect one or more outliers in a univariate data set that follows an approximately normal distribution.
This algorithm shows excellent performances with large dataset of more 50 images.
• Linear Fit Clipping [ConejeroPI]: It fits the best straight line (𝑦 = 𝑎𝑥 + 𝑏) of the pixel stack and rejects outliers.
This algorithm performs very well with large stacks and images containing sky gradients with differing spatial
distributions and orientations.

124 Chapter 7. Preprocessing

 Siril, Release 1.2.0

Rejection maps

The option Create rejection maps computes and creates rejection maps during stacking. These are images showing
how many images were rejected for each pixel of the result image, divided by the number of stacked images. If Merge
L+H is checked, Siril creates only one rejection map that will be the sum of the low and high maps.

Fig. 26: Example of a rejection map (L+H). We can very clearly see the trace of a satellite that has been removed.

Images filtering/weighting

The weighting allows to put a statistical weight on each image. In this way, the images considered to be the best will
contribute more than those considered to be the worst. Four methods of weighting are available:
• Number of stars weights individual frames based on number of stars computed during registration step.
• Weighted FWHM weights individual frames based on wFWHM computed during registration step. This is a
FWHM weighted by the number of stars in the image. For the same FWHM measurement, an image with more
stars will have a better wFWHM than an image with fewer stars.
• Noise weights individual frames based on background noise values.
• Number of images weights individual frames based on their integration time.

Median stacking

This method is mostly used for dark/flat/bias stacking. The median value of the pixels in the stack is computed for each
pixel.
√
The increase in SNR is proportional to 0.8 𝑁 and is therefore worse than stacking by average which is generally
preferred.

7.4. Stacking 125

Siril, Release 1.2.0

Pixel Maximum stacking

This algorithm is mainly used to construct long exposure star-trails images. Pixels of the image are replaced by pixels
at the same coordinates if intensity is greater.

Pixel Minimum stacking

This algorithm is mainly used for cropping sequence by removing black borders. Pixels of the image are replaced by
pixels at the same coordinates if intensity is lower.

7.4.2 Input normalisation methods

Normalisation will adjust the levels of each image against the reference image. This is particularly useful for mean
stacking with rejection, because rejecting pixels if the images show differences of levels is not very useful. They can
be caused by light nebulosity, light gradient caused by the moon or city lights, sensor temperature variation and so on.
This tends to improve the signal-to-noise ratio and therefore this is the option used by default with the additive normal-
isation.

If one of these 5 items is selected, a normalisation process will be applied to all input images before stacking.
• Normalisation matches the mean background of all input images, then, the normalisation is processed by mul-
tiplication or addition. Keep in mind that both processes generally lead to similar results but multiplicative
normalisation is prefered for image which will be used for multiplication or division as flat-field.
• Scale matches dispersion by weighting all input images. This tends to improve the signal-to-noise ratio and
therefore this is the option used by default with the additive normalisation.

Normalisa- Operation Use

tion case
None No normalisation are applied. dark/bias
frames
Additive Mean background values will be aligned through the application of additive opera-
tions.
Multiplicative Division will be used to align mean background values. flat
frames
Additive + In combination with additive background through additive matching, the images will light
Scaling be scaled to achieve dispersion matching. frames
Multiplicative In combination with background matching through division, the images will be
+ Scaling scaled to achieve dispersion matching.

Note: The bias and dark masters should not be processed with normalisation. However, multiplicative normalisation

126 Chapter 7. Preprocessing

 Siril, Release 1.2.0

must be used with flat-field frames.

Keep in mind that both processes generally lead to similar results but multiplicative normalisation is preferred for image
which will be used for multiplication or division as flat field.
Since the normalisation calculation step is usually a long one, as it requires determining all the statistics of the image, the
results are stored in the seq file. This way, if the user wants to do another stacking by changing the rejection parameters,
it will be executed more quickly. The Recompute option allows to force the recalculation of the normalisation.
By default, Siril uses IKSS estimators of location and scale to compute normalisation. For long sequences, computing
these estimators can be quite intensive. For such cases, you can opt in for faster estimators (based on median and
median absolute deviation) with the option Faster normalisation. While less resistant to outliers in each image, they
can still give a satisfactory result when compared to no normalisation at all.

7.4.3 Image rejection

It is also possible to reject a certain number of images in order to select only the best ones. This can be very useful for
Lucky DSO techniques where the number of images in a sequence is very high. One can choose between % and k-𝜎 to
either retain a given percentage of images or to calculate the allowable threshold using k-𝜎 clipping.

Several critieria are available:

• all: all images of the sequence are used in the stack.
• selected: only use image that have not been unselected from the sequence.
• FWHM: images with best computed FWHM (star-based registration only).
• weighted FWHM: this is an improvement of a simple FWHM. It allows to exclude much more spurious images
by using the number of stars detected compared to the reference image (star-based registration only).
• roundness: images with best star roundness (star-based registration only).
• background: images with lowest background values (star-based registration only).
• nb stars: images with best number of stars detected (star-based registration only).
• quality: images with best quality (planetary DFT or Kombat registrations).

7.4. Stacking 127

Siril, Release 1.2.0

7.4.4 Stacking result

• If Output Normalisation is checked, the final image will be normalized in the [0, 1] range if you work in 32-bit
format precision, or in [0, 65535] otherwise.

Warning: This option should not be checked for master stacking.

• If RGB equalization is checked, the channels in the final image will be equalized (color images only).
• The stacking result is saved under the name given in the text field. It is possible to use path parsing to build the
filename. A click on the overwrite button allows the new file created to overwrite the old one if it exists. If the
latter is not checked but an image with the same name already exists, then no new file is created.

7.4.5 References

128 Chapter 7. Preprocessing

 CHAPTER

EIGHT

PROCESSING

This section takes you through the different processing steps of your images. The drop-down menu is accessible from
the header bar using the Image Processing button. The tools are grouped in the menu, and in this documentation too,
by theme.

8.1 Image stretching

Image are stored as pixel values that come from the camera following a quasi-linear law, meaning that for areas of the
sky that show no visible feature, the pixel value will be close to zero, but for bright objects like stars it will be close to
a maximum value depending on exposure and gain. In between, if a nebula has a surface magnitude half of a star, it
will have pixel values half of those of the star and so on. This is what we call the linear pixel mode.
The human eye doesn't quite see photons like that. It amplifies dark areas, so that an object maybe a tenth as bright as
another would look half as bright. For astronomy images, we usually display images with a similar pixel value scaling
(see display modes from the GUI).
But it is only a display trick, using a screen transfer function, to render the pixel values of the untouched image to better
looking images.
Image stretching is about doing something similar but by modifying the pixel values of images instead of just altering
their rendering. Siril has three main tools to achieve this.

8.1.1 Asinh transformation

The asinh, or inverse hyperbolic sine, transformation will modify image pixel values in a way similar to what can be
seen with the asinh display pixel scaling function, which is parametrized by the low and high values cut-off cursors.
Here the parameters are the stretch factor and the black point value.
For monochrome images, pixel values are modified using the following function:

(original − blackpoint) × asinh(original × stretch)

pixel =
original × asinh(stretch)

For color images, the function becomes:

(original − blackpoint) × asinh(rgb_original × stretch)

pixel =
rgb_original × asinh(stretch)

where rgb_original is computed using the pixel values of the three channels.

Note: As rgb_original is an average of the 3 channels, one or two channel values will be greater than rgb_original
and can therefore clip. This can cause color artefacts when bright, strongly-colored regions are stretched. In order to

129
Siril, Release 1.2.0

Fig. 1: Image processing menu

130 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 2: Dialog box of Asinh Transformation

avoid this problem the RGB blend clipping algorithm is used. This was devised by the same authors as the Generalised
Hyperbolic Stretch transforms. The (𝑟, 𝑔, 𝑏) values are stretched first based on the luminance value rgb_original to give
(𝑟′ , 𝑔 ′ , 𝑏′ ). Then the original (𝑟, 𝑔, 𝑏) values are independently stretched to give (𝑟”, 𝑔”, 𝑏”). Finally the largest value
of 𝑘 is identified such that
𝑘 * 𝑟′ + (1 − 𝑘) * 𝑟”1;
𝑘 * 𝑔 ′ + (1 − 𝑘) * 𝑔”1;
and
𝑘 * 𝑏′ + (1 − 𝑘) * 𝑏”1
Then the transformed values are calculated as
(𝑘 * 𝑟′ + (1 − 𝑘) * 𝑟”, 𝑘 * 𝑔 ′ + (1 − 𝑘) * 𝑔”, 𝑘 * 𝑏′ + (1 − 𝑘) * 𝑏”)
This RGB blend clipping algorithm is also used for the Generalised Hyperbolic Stretch transforms described below.

When the Use RGB working space option is not ticked, rgb_original is the mean between the three pixel values; when it
is set, ponderation changes to 0.2126 for the red value, 0.7152 for the green value and 0.0722 for the blue value, which
gets results closer to color balance.

Siril command line

asinh [-human] stretch [offset]

Stretches the image to show faint objects using an hyperbolic arcsin transformation. The mandatory argument
stretch, typically between 1 and 1000, will give the strength of the stretch. The black point can be offset by providing
an optional offset argument in the normalized pixel value of [0, 1]. Finally the option -human enables using human

8.1. Image stretching 131

Siril, Release 1.2.0

eye luminous efficiency weights to compute the luminance used to compute the stretch value for each pixel, instead of
the simple mean of the channels pixel values. This stretch method preserves lightness from the L*a*b* color space

8.1.2 Midtone Transfer Function Transformation (MTF)

MTF is one of the most powerful tools for stretching the image. It can be easily automated and that's why the auto-
stretched view uses it.

Fig. 3: Dialog box of the Histogram Transformation

The tool is presented in the form of a histogram with 3 sliders (in the form of a triangle placed underneath) that we must
move to transform the image. The triangle on the left represents the shadow signal, the one on the right the highlights

132 Chapter 8. Processing

 Siril, Release 1.2.0

and finally, the one in the middle the midtone balance parameter. The values of these sliders are displayed below the
histogram, on the left, and can be changed directly by hand. Opposite is the percentage of pixels that are clipped by the
transformation: it is important not to clip too many pixels. If only the midtones parameter is changed, then no pixel
can be clipped.
The new pixel values are then computed with this function:

(𝑚 − 1)𝑥𝑝
MTF(𝑥𝑝 ) = (8.1)
(2𝑚 − 1)𝑥𝑝 − 𝑚

• For 𝑥𝑝 = 0, MTF = 0.
• For 𝑥𝑝 = 𝑚, MTF = 0.5.
• For 𝑥𝑝 = 1, MTF = 1.
where 𝑥𝑝 is the pixel value defined as follow

original − shadows
𝑥𝑝 = (8.2)
highlights − shadows

Note: It is generally not recommended to change the value of the highlights, otherwise they will become saturated
and information will be lost.

The toolbar contains many buttons that affect the visualization of the histogram. You can choose to display the input

histogram, the output histogram, the transfer curve and the grid. The button allows you to apply the same
transformation as the autostretch algorithm. It is rarely advisable to use this button as is. Adjustments are usually
necessary to avoid losing information. At the top of the histogram it is also possible to choose to display the histogram
in logarithmic view, as in the illustration. This behavior can be made default as explained here. Finally a zoom in X is
available. This is very useful when all the signal is concentrated on the left of the histogram.

Siril command line

mtf low mid high [channels]

Applies midtones transfer function to the current loaded image.

Three parameters are needed, low, midtones and high where midtones balance parameter defines a nonlinear
histogram stretch in the [0,1] range. For an automatic determination of the parameters, see AUTOSTRETCH.
Optionally the parameter [channels] may be used to specify the channels to apply the stretch to: this may be R, G, B,
RG, RB or GB. The default is all channels

Links: autostretch

Note: mtf is also a function that can be used in the PixelMath tool.

Siril command line

8.1. Image stretching 133

Siril, Release 1.2.0

autostretch [-linked] [shadowsclip [targetbg]]

Auto-stretches the currently loaded image, with different parameters for each channel (unlinked) unless -linked is
passed. Arguments are optional, shadowclip is the shadows clipping point, measured in sigma units from the main
histogram peak (default is -2.8), targetbg is the target background value, giving a final brightness to the image, range
[0, 1], default is 0.25. The default values are those used in the Auto-stretch rendering from the GUI.

Do not use the unlinked version after color calibration, it will alter the white balance

Applying transformation to the sequence

This transformation can easily be applied to a sequence. You just have to define the transformation on the loaded image
(with a sequence already loaded), then check the Apply to sequence button and define the output prefix of the new
sequence (stretch_ by default), or use the following command:

Siril command line

seqmtf sequencename low mid high [channels] [-prefix=]

Same command as MTF but for the sequence sequencename.

The output sequence name starts with the prefix "mtf_" unless otherwise specified with -prefix= option

Links: mtf

8.1.3 Generalised Hyperbolic Stretch transformations (GHS)

This is the most capable and modern tool of Siril, also the most complex to learn. A very detailed tutorial for this tool
in Siril was written by the authors of this algorithm: https://siril.org/tutorials/ghs. Here, we will just summarize here
the basic operation of this tool.
Simply put, the GHS is able to improve the contrast of a range of brightness levels in an image. For example, if one
wanted to better view the details in the medium to high brightness part of a nebula (which is in general very faint in an
astronomy image), it would be possible to only select this range for stretching. It is very good at improving the contrast
of main objects without making stars too big. The tool is very much based on iterative use, so stretching all the different
ranges of brightnses in the image one after the other, by small touches.
To achieve this, the tool relies heavily on histogram display and interaction, for each color channel. The transformation
function, shaped like a hyperbole or an 'S', can be altered by moving its center (the SP - symmetry point parameter),
by flattening either of its ends (with shadow and highlight protections), and of course its twist (stretch D and local
stretch b factors). Manipulating these parameters on a small (for speed) image with an SP value of 0.5 will help you
understanding their effect.

134 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 4: Dialog box of the Generalized Hyperbolic Stretch

8.1. Image stretching 135

Siril, Release 1.2.0

There are two main operations to do on each iteration: selecting the range of lights to modify, and actually modifying
it. Selecting the range is quite easy, it's a matter of finding a representative value (SP) and defining the width of the
range (b). Setting SP can be done in three ways:
• selecting an area of similar brightness in the image and clicking on the picker button
• clicking on the histogram itself with a single left click (it is possible to zoom in the histogram using the + button
at the top left)
• using the cursor or its associated plus and minus buttons or direct value.
The width of the range depends on the local stretch. A high value of b will make a small range, and increase contrast
over a small range of brightnesses in the image.
Modifying the histogram once the location of the change has been set is a more complex operation. One goal given
by the algorithm's authors is to make the logarithmic view of the histogram (enabled by checking the box) as close as
possible to a decreasing line. To do this, bumps need to be carved out and valleys to be filled. Here is a quick guide of
values to use depending on what needs to be achieved:
• initial stretch from linear: set SP slightly to the left of the main peak, moderate b value from 6 and up, increase
D slightly only to start to see the main object. Do not stretch too much at this point like an autostretch would do,
otherwise the stars would grow too big (main tutorial section for this).
• improving contrast of a range, or filling a valley: set SP to the centre of the valley in the histogram, set b as
high as how narrow the range or valley is, decrease HP to preserve stars, increase D slowly until the improvement
appears.
• decreasing contrast of a range, or flattening a peak: decreasing a peak is not easy to do but will happen as a
side effect of valleys being filled. For example, creating a peak, or filling a valley, will decrease what is on the
left of SP. Another possibility is to use the inverse transformation, from the Type of stretch combo box, and a
high LP value, and HP at 1.
• move curve to the left, making the image darker: often if we stretched the entire histogram, the peak will
move to the right, making the background too bright. There is a simple way to just move everything to the left,
select in the Type of stretch combo box the last entry, Linear stretch (BP shift). There's only one cursor to move
now, controlling how much it will shift.
Some operations are also common for color images, where we often want to have a similar shape of curve for the
three channels, working on each channel independently by unselecting them with the three colored circles below the
histogram view:
• moving the peak to the right: a simple strech with a SP value left of the peak will do that in general, so this
should be done as part of a stretch.
• spreading a peak: to stretch a channel a bit more and it give it more importance in the final result, without
changing the location of the peak too much, set SP near the peak or slightly to its right, set b depending on how
the contribution is expected throughout the channel, between a negative value if the impact shall be felt up to
the stars levels (to change their color) and a high value if this is only for a nebula, increase D to obtain the target
width of the peak, and then offset the peak to the left by increasing HP.
• moving all channels together: an alternative luminance mapping stretch exists, see the Color stretch model
combo box at the top right of the GHS window, using either luminance stretch values will stretch the luminance
and reapply colors on it instead of stretching directly the three channels. The luminance modes can be better
at preserving colours in the image. These modes use the same RGB blend clipping mode described above to
prevent color channel clipping artefacts.
• remapping image saturation: the GHS transforms can be applied to the image saturation channel by selecting
the Saturation option from the Color stretch model combo box. When this mode is selected the pre- and post-
stretch saturation histograms will be shown in yellow. All the GHS options are available and this mode can
provide highly targeted adjustment of the image saturation channel. A simple method of increasing the saturation
in relatively unsaturated regions while preventing oversaturation is to use an Inverse generalised hyperbolic

136 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 5: The Generalized Hyperbolic Stretch with a color image

8.1. Image stretching 137

Siril, Release 1.2.0

transform stretch with SP set to around 0.5, and HP brought down low enough to flatten the upper end of the
saturation histogram.

Fig. 6: The image above shows how applying the GHS tool to the saturation channel gives an easy way of strongly
enhancing saturation in a low-saturation image while still retaining control of the upper end of the saturation histogram,
here used to create a 'Mineral Moon' image highlighting the differing mineral composition of different regions of the
lunar surface.

Siril command line

ght -D= [-B=] [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat] [channels]

Generalised hyperbolic stretch based on the work of the ghsastro.co.uk team.

The argument -D= defines the strength of the stretch, between 0 and 10. This is the only mandatory argument. The
following optional arguments further tailor the stretch:
B defines the intensity of the stretch near the focal point, between -5 and 15;
LP defines a shadow preserving range between 0 and SP where the stretch will be linear, preserving shadow detail;
SP defines the symmetry point of the stretch, between 0 and 1, which is the point at which the stretch will be most
intense;
HP defines a region between HP and 1 where the stretch is linear, preserving highlight details and preventing star
bloat.
If omitted B, LP and SP default to 0.0 ad HP defaults to 1.0.
An optional argument (either -human, -even or -independent) can be passed to select either human-weighted or
even-weighted luminance or independent colour channels for colour stretches. The argument is ignored for mono
images. Alternatively, the argument -sat specifies that the stretch is performed on image saturation - the image must
be color and all channels must be selected for this to work.

138 Chapter 8. Processing

 Siril, Release 1.2.0

Optionally the parameter [channels] may be used to specify the channels to apply the stretch to: this may be R, G, B,
RG, RB or GB. The default is all channels

Siril command line

invght -D= [-B=] [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat] [channels]

Inverts a generalised hyperbolic stretch. It provides the inverse transformation of GHT, if provided with the same
parameters, undoes a GHT command, possibly returning to a linear image. It can also work the same way as GHT but
for images in negative

Links: ght

Siril command line

modasinh -D= [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat] [channels]

Modified arcsinh stretch based on the work of the ghsastro.co.uk team.

The argument -D= defines the strength of the stretch, between 0 and 10. This is the only mandatory argument. The
following optional arguments further tailor the stretch:
LP defines a shadow preserving range between 0 and SP where the stretch will be linear, preserving shadow detail;
SP defines the symmetry point of the stretch, between 0 and 1, which is the point at which the stretch will be most
intense;
HP defines a region between HP and 1 where the stretch is linear, preserving highlight details and preventing star
bloat.
If omitted LP and SP default to 0.0 ad HP defaults to 1.0.
An optional argument (either -human, -even or -independent) can be passed to select either human-weighted or
even-weighted luminance or independent colour channels for colour stretches. The argument is ignored for mono
images. Alternatively, the argument -sat specifies that the stretch is performed on image saturation - the image must
be color and all channels must be selected for this to work.
Optionally the parameter [channels] may be used to specify the channels to apply the stretch to: this may be R, G, B,
RG, RB or GB. The default is all channels

Siril command line

invmodasinh -D= [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat] [channels]

Inverts a modified arcsinh stretch. It provides the inverse transformation of MODASINH, if provided with the same
parameters, undoes a MODASINH command, possibly returning to a linear image. It can also work the same way as

8.1. Image stretching 139

Siril, Release 1.2.0

MODASINH but for images in negative

Links: modasinh

Siril command line

linstretch -BP= [-sat] [channels]

Stretches the image linearly to a new black point BP.

The argument [channels] may optionally be used to specify the channels to apply the stretch to: this may be R, G, B,
RG, RB or GB. The default is all channels.
Optionally the parameter -sat may be used to apply the linear stretch to the image saturation channel. This argument
only works if all channels are selected

Applying transformation to the sequence

This transformation can easily be applied to a sequence. You just have to define the transformation on the loaded image
(with a sequence already loaded), then check the Apply to sequence button and define the output prefix of the new
sequence (stretch_ by default). All of the commands have a sequence processing form too. Each sequence stretching
command starts with seq and the first argument must be the sequence name, but they are otherwise the same.

Siril command line

seqght sequence -D= [-B=] [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat]␣
˓→[channels] [-prefix=]

Same command as GHT but the sequence must be specified as the first argument. In addition, the optional argument
-prefix= can be used to set a custom prefix

Links: ght

Siril command line

seqinvght sequence -D= [-B=] [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat]␣
˓→[channels] [-prefix=]

Same command as INVGHT but the sequence must be specified as the first argument. In addition, the optional
argument -prefix= can be used to set a custom prefix

140 Chapter 8. Processing

 Siril, Release 1.2.0

Links: invght

Siril command line

seqmodasinh sequence -D= [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat]␣
˓→[channels] [-prefix=]

Same command as MODASINH but the sequence must be specified as the first argument. In addition, the optional
argument -prefix= can be used to set a custom prefix

Links: modasinh

Siril command line

seqinvmodasinh sequence -D= [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat]␣
˓→[channels] [-prefix=]

Same command as INVMODASINH but the sequence must be specified as the first argument. In addition, the
optional argument -prefix= can be used to set a custom prefix

Links: invmodasinh

Siril command line

seqlinstretch sequence -BP= [channels] [-sat] [-prefix=]

Same command as LINSTRETCH but the sequence must be specified as the first argument. In addition, the optional
argument -prefix= can be used to set a custom prefix

Links: linstretch

8.1. Image stretching 141

Siril, Release 1.2.0

8.2 Colors

8.2.1 Color Calibration

Siril offers two ways to retrieve the colors of your image. Here, "retrieve" means re-balancing the RGB channels to get
as close as possible to the true colors of the shot object.

Manual Color Calibration

Warning: The color calibration must be performed on a linear image whose histogram has not yet been stretched.
Otherwise, the colors obtained are not guaranteed to be correct.

The manual way uses the following window:

The first step deals with the background of your image. The goal is to equalize the RGB layers in order the background
appears as a neutral grey color.
After making a selection in your image (in a not so crowdy nor contrasted area), the area is taken into account by clicking
on the Use current selection button. The coordinates of the rectangle are displayed. Then Background Neutralization
will calculate the median of each channel and equalize them.
The second step deals with the bright objetcs of the picture. You can modify once again the histogram in two ways:
• Manually, with White reference and the 3 R, G and B coefficients, according to your own taste.
• Automatically, by selecting a rectangle area with contrasted objects (the same way as previously)
Two sliders allow you to change the rejection limit for too dark and too bright pixels in the selection.
As this is a trial and error process, you can undo the result with the Undo button (up left) and then try with other
selections or coefficients until you are satisfied.

Photometric Color Calibration

Warning: The calibration of the colors by photometry must imperatively be carried out on a linear image whose
histogram was not yet stretched. Without what, the photometric measurements will be wrong and the colors obtained
without guarantee of being correct.

Another way for retrieving the colors is to compare the color of the stars in the image with their color in catalogues, to
obtain the most natural color in an automatic and non-subjective way. This is the PCC (Photometric Color Calibration)
tool. It can only work for images taken with a set of red, green and blue filters for colors, or on-sensor color. To identify
stars within the image with those of the catalogue, an astrometric solution is required. Running the PCC tool will first
do that, so for this first part, please see the documentation of the plate solver module.

Note: This technique is heavily dependent on the type of filter used. Using different kinds of R, G, B filters will
not make a large difference, but using a Light pollution filter or no IR-block filters will make the solution deviate
significantly and not give the expected colors.

Since version 1.2, the two tools run independently: it is possible to run the photometric analysis and color correction of
the image only if the image has been already plate solved. It also means different catalogues can be used for PCC and

142 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 7: Manual Color Calibration dialog window.

8.2. Colors 143

Siril, Release 1.2.0

astrometry. And now, the tool is also available as the pcc command, so it can be embedded in image post-processing
scripts.
If the image was previously plate solved, turn on the annotations feature to check that catalogues align with the image.
If the astrometric solution is not good enough, checking Force plate solving will force its recomputation as part of the
PCC process.
As a reminder from the plate solver documentation, here is a summary of the options visible in the window:
• Make sure the sampling is correct, computed from the focal length and pixel size found in the image or copied
from the settings.
• The Flip image if needed allows to reorient the image correctly according to the astrometry result.
• For some oversampled or too large images, it is useful to check the Downsample image to have more chances of
success with the plate solving and it's also faster.
• The Auto-crop (for wide field) option will limit the field to 5 degrees in case you are dealing with very wide field
images, mostly useful for plate solving.
• The Catalog Settings section allows you to choose which photometric catalog should be used, NOMAD or
APASS, as well as the limiting magnitude.

Tip: The NOMAD catalog can be installed locally, while the APASS catalogue needs an internet access to get
its content.

• The Star Detection section allows you to manually select which stars will be used for the photometry analysis.
It's better to have hundreds of them at least, so individual picking would not be ideal.
• If desired, the Background Reference can be manually selected as described in Manual Color Calibration. This
can be useful in the case of nebula images where the background sky parts are small.
When enough stars are found and the astrometric solution is correct, the PCC will print this kind of text in the Console
tab:

Applying aperture photometry to 433 stars.

70 stars excluded from the calculation
Distribution of errors: 1146 no error, 18 not in area, 48 inner radius too small, 4␣
˓→pixel out of range

Found a solution for color calibration using 363 stars. Factors:

K0: 0.843 (deviation: 0.140)
K1: 1.000 (deviation: 0.050)
K2: 0.743 (deviation: 0.130)
The photometric color correction seems to have found an imprecise solution, consider␣
˓→correcting the image gradient first

We can understand that 433 stars were selected from the catalogue and the image for photometric analysis, but somehow,
only 363 we actually used, 70 being excluded. The line Distribution of errors explains for what reason they were
excluded: 18 were not found in the expected position, 48 were too big and 4 probably saturated. It is very common to
have many stars rejected because they don't meet the strict requirements for a valid photometric analysis.
We can also see that the PCC found three coefficients to apply to the color channels to correct the white balance. The
deviation here, which is the average absolute deviation of the color correction for each of the star of the photometric
set, is moderately high. On well calibrated images without gradient, with correct filters and without a color nebula
covering the whole image, devation would get closer to 0.

Siril command line

144 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 8: Photometric Color Calibration dialog window.

8.2. Colors 145

Siril, Release 1.2.0

pcc [image_center_coords] [-noflip] [-platesolve] [-focal=] [-pixelsize=] [-limitmag=[+-

˓→]] [-catalog=] [-downscale]

Run the Photometric Color Correction on the loaded image.

If the image has already been plate solved, the PCC can reuse the astrometric solution, otherwise, or if WCS or other
image metadata is erroneous or missing, arguments for the plate solving must be passed:
the approximate image center coordinates can be provided in decimal degrees or degree/hour minute second values
(J2000 with colon separators), with right ascension and declination values separated by a comma or a space.
focal length and pixel size can be passed with -focal= (in mm) and -pixelsize= (in microns), overriding values from
image and settings.
you can force the plate solving to be remade using the -platesolve flag.

Unless -noflip is specified and the image is detected as being upside-down, the image will be flipped if a plate solving
is run.
For faster star detection in big images, downsampling the image is possible with -downscale.

The limit magnitude of stars used for plate solving and PCC is automatically computed from the size of the field of
view, but can be altered by passing a +offset or -offset value to -limitmag=, or simply an absolute positive value for
the limit magnitude.
The star catalog used is NOMAD by default, it can be changed by providing -catalog=apass. If installed locally, the
remote NOMAD (the complete version) can be forced by providing -catalog=nomad

Links: nomad

8.2.2 Color Saturation

This tool is used to increase the color saturation of the image. It is possible to choose between a specific hue or the
global hue to enhance. The strength of the saturation is adjusted with the slider Amount.
The Background factor slider sets the factor multiplied by the background value. Lower is the value, stronger is the
saturation effect. While a high value will preserve the background.

Siril command line

satu amount [background_factor [hue_range_index]]

146 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 9: Color Saturation dialog window.

Enhances the color saturation of the loaded image. Try iteratively to obtain best results.
amount can be a positive number to increase color saturation, negative to decrease it, 0 would do nothing, 1 would
increase it by 100%
background_factor is a factor to (median + sigma) used to set a threshold for which only pixels above it would be
modified. This allows background noise to not be color saturated, if chosen carefully. Defaults to 1. Setting 0 disables
the threshold.
hue_range_index can be [0, 6], meaning: 0 for pink to orange, 1 for orange to yellow, 2 for yellow to cyan, 3 for
cyan, 4 for cyan to magenta, 5 for magenta to pink, 6 for all (default)

8.2.3 Remove Green Noise

Because green is not naturally present in deep sky images (except for comets and some planetary nebulae), if the image
has already been calibrated, its colors are well balanced and the image is free of any gradient, we can assume that if the
image contains green, it belongs to the noise. It is then interesting to find a method to remove this dominant green. This
is exactly what the Remove Green Noise tool proposes, which is derived from the Subtractive Color Noise Reduction
tool, but for green only.

Warning: This tool is not intended for direct use on a typical green image from a stack where the background sky
level has not been equalized. Its use in such conditions would destroy the image's chrominance.

This tool has 3 settings. The protection method, the amount (called 𝑎 in the following section), and a Preserve lightness
button. The following methods present the different existing ways to remove the green pixels by replacing them with a
mix of Red and Blue. The amount is only available for methods with mask protection. The choice of its value must be
done with caution in order to minimize the rise of the magenta cast in the sky background. Do not hesitate to use the

8.2. Colors 147

Siril, Release 1.2.0

Fig. 10: Remove Green Noise dialog window.

Undo and Redo buttons in order to fine-tune the value.

Protection method

Maximum Mask Protection

𝑚 = max(𝑅, 𝐵)
𝐺′ = 𝐺 × (1¯𝑎) × (1¯𝑚) + 𝑚 × 𝐺

Additive Mask Protection

𝑚 = min(1, 𝑅 + 𝐵)
𝐺′ = 𝐺 × (1¯𝑎) × (1¯𝑚) + 𝑚 × 𝐺

Average Neutral Protection (default method)

𝑚 = 0.5 × (𝑅 + 𝐵)
𝐺′ = min(𝐺, 𝑚)

Maximum Neutral Protection

𝑚 = max(𝑅, 𝐵)
𝐺′ = min(𝐺, 𝑚)
Finally, the Preserve lightness button preserves the original CIE L* component in the processed image, in order to only
process chromatic component, it is highly recommended to let this option checked.

Siril command line

rmgreen [-nopreserve] [type] [amount]

148 Chapter 8. Processing

 Siril, Release 1.2.0

Applies a chromatic noise reduction filter. It removes green tint in the current image. This filter is based on
PixInsight's SCNR and it is also the same filter used by HLVG plugin in Photoshop.
Lightness is preserved by default but this can be disabled with the -nopreserve switch.

Type can take values 0 for average neutral, 1 for maximum neutral, 2 for maximum mask, 3 for additive mask,
defaulting to 0. The last two can take an amount argument, a value between 0 and 1, defaulting to 1

8.2.4 Negative Transform

Negative transformation refers to subtracting pixel values from (𝐿1), where 𝐿 is the maximum possible value of the
pixel, and replacing it with the result.

The Negative transformation tool is different from the negative view in the toolbar. Indeed, the transformation
is not only visual, but actually applied to the pixel values. If you save the image, it will be saved as a negative.

Fig. 11: Original image with weak signal (Image Cyril Richard).

Tip: A common use of the negative transformation tool is to remove the magenta cast from SHO images. In this case
one need to apply Negative transformation, then Remove Green Noise, then Negative transformation again.

8.2. Colors 149

Siril, Release 1.2.0

Fig. 12: Negative image where the signal is more visible (Image Cyril Richard).

150 Chapter 8. Processing

 Siril, Release 1.2.0

Siril command line

neg

Changes pixel values of the currently loaded image to a negative view, like 1-value for 32 bits, 65535-value for 16
bits. This does not change the display mode

8.3 Filters

This section presents all the filters present in Siril. Filters are tools that will modify the pixels of the image according
to the needs.

8.3.1 À Trous Wavelets Transform

A wavelet is a function at the base of the wavelet decomposition, a decomposition similar to the short term Fourier trans-
form, used in signal processing. It corresponds to the intuitive idea of a function corresponding to a small oscillation,
hence its name.
There are many types of wavelet functions that have their own names, as shown in the figure below.
The À Trou Wavelet Transform used in Siril performs decomposition of an image into a series of scale layers, also
known as wavelet layers. These layers can be extracted with the Wavelet Layers extraction tool, however here, they
are used without being visually accessible. In general, this algorithm is widely used at the end of a planetary image
stack. Because the noise is exclusively contained in one of the wavelet layers, it is possible to bring out the details of
the image by containing the noise amount.
The first thing to do is to click on the Execute button in order to calculate the wavelet layers using the parameters defined
above, such as:
• Type: There are two types of algorithms possible: Linear and BSpline. The latter will usually be chosen, even
if it is a bit slower.
• Nb of layers: Number of wavelet layers that will be used. 6 is the maximum number of layers that can be defined.
To work on a larger number of layers it is possible to use the command line explained below.
Then, each layer has a slider that allows to modify the contrast of this layer. If less than 6 layers have been created, then
only the corresponding sliders will be active. A value greater than 1 improves the details while a smaller value tends
to reduce them.
This is a liveview tool. The changes are displayed in real time and you have to click on Apply to validate them. Clicking
on Reset resets all the sliders to 1, and thus cancels any transformation in progress.

Siril command line

wavelet nbr_layers type

Computes the wavelet transform of the loaded image on (nbr_layers=1...6) layer(s) using linear (type=1) or bspline
(type=2) version of the 'à trous' algorithm. The result is stored in a file as a structure containing the layers, ready for

8.3. Filters 151

Siril, Release 1.2.0

Morlet Daubechies order 2

1 0.4

0.3
0.5

0.2

0
0.1

0
-0.5

-0.1

-1
-4 -2 0 2 4 -0.2
-1 -0.5 0 0.5 1 1.5 2
Complex Shannon Mexican hat
1.5 1

0.8
1

0.6

0.5
0.4

0.2
0

-0.5
-0.2

-1 -0.4
-4 -2 0 2 4 -4 -2 0 2 4

Fig. 13: An example of four different types of wavelets.

152 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 14: Wavelet tool dialog box.

8.3. Filters 153

Siril, Release 1.2.0

Fig. 15: Wavelets applied on a Jupiter image (courtesy of J.-L. Dauvergne). The image on the left is the raw image of
the stacking output, while the image on the right is the same image on which wavelets are applied.

weighted reconstruction with WRECONS.

See also EXTRACT

Links: wrecons, extract

Siril command line

wrecons c1 c2 c3 ...

Reconstructs to current image from the layers previously computed with wavelets and weighted with coefficients c1,
c2, ..., cn according to the number of layers used for wavelet transform, after the use of WAVELET

Links: wavelet

The example given in the image above would be written in the command line as follow:

wavelet 6 2
wrecons 31 5 1 1 1 1

154 Chapter 8. Processing

 Siril, Release 1.2.0

8.3.2 Banding Reduction

In some cases, images may suffer from a banding defect. This is usually caused by the sensor and calibration by darks,
bias and flats do not improve the images.

Fig. 16: Original image with visible banding.

The banding reduction window dialog has some parameters to optimize the processing:
• Amount defines the strength of the correction. The higher the value, the stronger the correction.
• Protect from Highlights will ignore bright pixels when the option is checked.
• 1/Sigma Factor will adjust the highlight protection. Higher value will give a better protection.
• Vertical banding allows user to fix banding if bands are vertical.
Applying the following filter to the original image, with parameter values as shown in the illustration, gives a nice result
free of banding.
This transformation can easily be applied to a sequence. You just have to define the transformation on the loaded image
(with a sequence already loaded), then check the Apply to sequence button and define the output prefix of the new
sequence (unband_ by default).

Siril command line

fixbanding amount sigma [-vertical]

8.3. Filters 155

Siril, Release 1.2.0

Fig. 17: Banding Reduction dialog box.

Fig. 18: Result after the filter has been run. No more bandings are visible.

156 Chapter 8. Processing

 Siril, Release 1.2.0

Tries to remove the horizontal or vertical banding in the loaded image.

amount defines the amount of correction, between 0 and 4.
sigma defines the highlight protection level of the algorithm, higher sigma gives higher protection, between 0 and 5.
Values of 1 and 1 are often good enough.
-vertical option enables to perform vertical banding removal, horizontal is the default

Siril command line

seqfixbanding sequencename amount sigma [-prefix=] [-vertical]

Same command as FIXBANDING but for the sequence sequencename.

The output sequence name starts with the prefix "unband_" unless otherwise specified with -prefix= option

Links: fixbanding

8.3.3 Contrast-Limited Adaptive Histogram Equalization (CLAHE)

The CLAHE method is used to improve the contrast of images. It differs from ordinary histogram equalization in
that the adaptive method calculates multiple histograms, each corresponding to a separate section of the image, and
uses them to redistribute the brightness values of the image. It can therefore improve local contrast and enhance edge
definition in each region of an image.

Fig. 19: Dialog box of the Contrast-Limited Adaptive Histogram Equalization filter.

8.3. Filters 157

Siril, Release 1.2.0

Tip: This filter is a liveview filter. In other words, every change in the settings is automatically visible on the screen,
but this can be disabled by unchecking the Preview button.

• The size of the tiles, in which the histograms are calculated, can be defined via a slider. By default it is set to 8.
• The Clip Limit is the option that prevents to overamplify noise in relatively homogeneous regions of an image.
Then, the clipped part of the histogram that exceeds the clipping limit is redistributed equally among all the bins
of the histogram.

Tip: This filter works better on non-linear data. It is recommended to stretch the image before.

Fig. 20: An example of CLAHE filter applied to a non-linear data with Tiles Grid Size=21 and Clip Limit=4.
20.

Siril command line

clahe cliplimit tileSize

Equalizes the histogram of an image using Contrast Limited Adaptive Histogram Equalization.

cliplimit sets the threshold for contrast limiting.

tilesize sets the size of grid for histogram equalization. Input image will be divided into equally sized rectangular tiles

158 Chapter 8. Processing

 Siril, Release 1.2.0

8.3.4 Cosmetic Correction

In Siril, the cosmetic correction is the step that gets rid of hot and cold pixels in the image. It is usually done during
pre-processing using the master-dark. This is because the latter usually contains a good map of the defective pixels and
it is easier to find them on it. However, when you don't have a master-dark, Siril offers an alternative with an automatic
detection algorithm of these pixels in a light image.

Fig. 21: Dialog window of Correction Cosmetic tool.

The dialog window contains several parameters necessary for the proper functioning of the tool. However, using the
default settings usually gives good results.
• Cold Sigma: How many times (in average deviation units) a pixel value must differ from the value of surrounding
neighbors to be considered as a cold pixel.
• Hot Sigma: How many times (in average deviation units) a pixel value must differ from the value of surrounding
neighbors to be considered as a hot pixel.
• Amount: This is a modulation parameters where 0 means no correction and 1, 100% corrected.
• CFA: This option needs to be checked for CFA images with Bayer pattern. It does not work for X-Trans sensor.
This operation can be applied to sequences. Open a sequence and prepare the settings you want to use, then check the
Apply to sequence button and define the output prefix of the new sequence (cc_ by default).

Hot pixels detection

Let's call 𝑚5×5 the median of the 5 nearest neighbors. If the pixel value is greater than

𝑚5×5 + max(avgDev, 𝜎high × avgDev),

with avgDev, the Average Deviation of the whole image.

Then the pixel is replaced by the average of the 3 × 3 pixels: 𝑎3×3 , but only if

avgDev
𝑎3×3 < 𝑚5×5 + .
2

8.3. Filters 159

Siril, Release 1.2.0

Cold pixels detection

If the pixel value is less than

𝑚5×5 − (𝜎low × avgDev),

then the pixel is replaced by 𝑚5×5 .

Fig. 22: Animation showing cosmetic correction.

Siril command line

find_cosme cold_sigma hot_sigma

Applies an automatic detection and replacement of cold and hot pixels in the loaded image, with the thresholds
passed in arguments in sigma units

Siril command line

find_cosme_cfa cold_sigma hot_sigma

Same command as FIND_COSME but for CFA images

Links: find_cosme

8.3.5 Deconvolution

Deconvolution is a mathematical tool to compensate for blurring or distorting effects in an image. The true scene is
not what is recorded on your sensor - you record an estimate of the true scene convolved by a PSF (in mathematical
terms, the "blurring PSF" that represents atmospheric distortion, physical properties of your telescope, motion blur
and so on, degrading your estimate). Deconvolution can, to an extent, reverse this image degradation. However, it
is important to say up front that deconvolution is what mathematicians call an ill-posed problem (like most inverse
problems). Ill-posed means that either a solution may not exist, if a solution does exist it may not be unique, and it may
not have continuous dependence on the data. Essentially it means deconvolution is, even theoretically, really hard and
there are no guarantees it will work.
All this is made even harder when we don't know exactly what the PSF is that we're trying to remove. In astronomy we
can in theory get an idea of the PSF by the effect of blurring on the point sources (stars) that we are imaging. However
sometimes the true PSF isn't constant across the image, sometimes other factors such as star saturation prevent the star
PSF being an entirely accurate estimate of the PSF, and sometimes (for example lunar imaging) there are no stars.
Siril aims to provide a flexible approach to deconvolution. There are several options for defining or estimating the PSF,
and several deconvolution algorithms to choose from for the final stage of deconvolution once the PSF is defined.
Deconvolution is accessed through the Image Processing menu or using Siril commands.

160 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 23: Example of deconvolution on star field.

Fig. 24: Dialog box of the deconvolution tool.

8.3. Filters 161

Siril, Release 1.2.0

Overview of Usage

• To generate a deconvolution PSF, select the required PSF generation method and press Generate PSF. This can
be performed separately from the actual deconvolution so that the user can see the effect of changing the PSF
parameters.
• Siril only generates monochrome PSFs as this is the most common use case and simplifies the user interface.
However, three monochrome PSFs can be saved and composited to produce a 3-channel PSF which can be loaded
and used to deconvolve 3-channel images.
• To apply deconvolution to a single image, select the required PSF generation method and press Apply. If a blind
PSF estimation method has previously been run, the method will automatically be set to Previous PSF, in order
to avoid unnecessarily recalculating the PSF.
• To apply deconvolution to a sequence, proceed as above but ensure that you activate the Apply to Sequence
checkbox. You may also specify a custom prefix to give to the output sequence: if no other prefix is provided,
the default (dec_) will be used.
• When deconvolving a sequence, the PSF will be calculated only for the first image. The same PSF will be re-used
for all images in the sequence.

Overview of Blur Kernel Definition Methods

• 0 Descent: This is the default PSF estimation method based on work by Anger, Delbracio and Facciolo. The
parameters do not generally require adjustment, except that for particularly large PSFs you may wish to try the
multiscale PSF estimation model. Multiscale is off by default as during development it was noted to have a
tendency to produce rather unnatural results with the more common small to medium PSF sizes.
• Spectral Irregularities [Goldstein2012]: This PSF estimation method is offered as an alternative. In general
it does not perform as well as the 0 descent method, however it may be useful if you discover an image where
the default method does not give good results. For this method the latent sharp image needs not to contain any
edges as long as the spectral decay model is respected. On the other hand, the 0 descent assumes a similar model
(since edges have the same spectral decay), but requires to have sparse gradients and be contrasted, thus edges to
be in-phase, so theoretically this model may work better on low contrast starless images. Some experimentation
is likely required to find the algorithm that best fits your data.
• PSF From Stars: This method models a PSF from the average PSF of the selected stars. It is important to be
selective about the stars you choose: they must not be saturated as that would give a gross distortion of the PSF
estimate, but they must also not be so faint that Siril's star analysis functions provide inaccurate measurements
of the stars. The stars chosen should be reasonably bright, fairly central to the image and in an area of the image
with a fairly constant background. Once stars are selected, you can pick either a Gaussian or Moffat star profile
model and when executing the deconvolution the PSF will be synthesized from the average parameters of the
selected stars. If no stars are selected, Siril will attempt to autodetect stars with a peak amplitude between 0.07
and 0.7, with a Moffat profile. This range avoids saturated stars as well as those that are too faint to give an
accurate solution, and generally provides good results.
• Manual PSF: This method allows you to define a PSF manually. Gaussian, Moffat or disc PSF models can
be defined. Note that the FWHM is specified in pixels, not arc seconds. The Gaussian and Moffat models are
suitable for deconvolving the shapes of stars resulting from atmospheric distortion; the disc PSF model is suitable
for deconvolving the effect of being slightly out of focus.
• Load PSF from file: This method allows you to load a PSF from any image format supported by Siril. The
provided PSF must be square (it will be rejected if not square) and should be odd (it will be cropped by one pixel
in each direction if not odd, but this will give a slightly off-centre PSF and is not optimal compared with providing
an odd PSF in the first place). Either monochrome or 3-channel PSFs may be loaded. If a 3-channel PSF is loaded
in conjunction with a monochrome image, the evenly-weighted luminance values of the PSF will be used. If a
3-channel PSF is loaded together with a 3-channel image then each channel of the image will be deconvolved

162 Chapter 8. Processing

 Siril, Release 1.2.0

using the corresponding channel of the PSF. If a monochrome PSF is loaded together with a 3-channel image
then the image will be converted to the LAB colour space and the L (Luminance) channel will be deconvolved
using the monochrome PSF for computational efficiency, and the deconvolved L will be recombined with the A
and B channels and converted back to RGB.
• Previous PSF: This method allows reuse of the previously estimated PSF. It is mostly of use with the blind
PSF estimation methods: if you are content with the estimated PSF but wish to make a number of test runs
using different parameters for the final stage of deconvolution, you can reuse the previous PSF and save some
computation time.
• Once estimated, PSFs may be saved if desired. If Siril is compiled with libtiff support then the PSF will be saved
in 32-bit TIFF format, with the same filename as the current image but date-and-time-stamped and suffixed
with _PSF. If Siril has been built without libtiff support, the PSF will be saved as a FITS file. While this is
Siril's primary format for astronomical image files, TIFF is preferred for PSFs: the disadvantage of using the
FITS format for PSFs is potential reduced compatibility with image editors that you may wish to use to edit or
examine the saved file.

Tip: If the blind generation of a deconvolution PSF can be done on linear and non-linear data, the use of a PSF from
star PSF can only be done on linear images. Otherwise the PSF values would not be valid.

Overview of Non-Blind Deconvolution

• Richardson-Lucy Deconvolution [Lucy1974]: This is the default non-blind deconvolution algorithm. It is an

iterative method, famous for its use in correcting image distortions in the early operating period of the Hubble
Space Telescope, and in Siril is regularized using either the Total Variation method, which aims to penalize
the algorithm for amplifying noise, or the Frobenius norm of the local Hessian matrix. This regularization is
based on second derivatives. As well as regularization an early stopping parameter is provided, which allows the
algorithm to be halted early once its rate of convergence falls below a certain level. Increasing the value of the
early stopping parameter can reduce ringing around stars and sharp edges. Two formulations of the Richardson-
Lucy algorithm are provided: the multiplicative formulation and the gradient descent formulation. The latter
can allow better control, as the gradient descent step size can be altered (the downside of this is that by using
more small steps, more iterations are required to reach the same level of convergence). The bigger advantage
of the gradient descent method is that it allows more regularization to be used - this can be problematic in the
multiplicative Richardson-Lucy algorithm as the regularization term appears in the denominator and small values
here (strong regularization) can cause instability. Siril will use naive convolution for small kernel sizes and FFT-
based convolution for larger kernel sizes where FFTs provide a more efficient algorithm. (This is automatic and
requires no user intervention.)
• Wiener Filtering Method: This method is a non-iterative deconvolution method. It models an assumed Gaus-
sian noise profile, i.e. noise modelled by a constant profile. The constant alpha is used to set the regularization
strength in relation to the noise level. As with the other algorithms, a smaller value of alpha provides more reg-
ularization. This algorithm can be good for lunar images where the noise regime is Gaussian not Poisson, but
usually works badly on deep space imagery where the noise still tends to have a Poisson character.
• Split Bregman Method: This method is used internally within the blur PSF estimation processes, and is also
offered as a final stage deconvolution algorithm. It is a commonly used algorithm in solving convex optimization
problems. This algorithm is also regularized using a total variation cost function. It does not perform as well as
Richardson-Lucy on starscapes but may be considered for starless images or lunar surface images.

Tip: Choice of deconvolution method is very important to obtaining good results. Generally for DSO images it is
important to use a Richardson-Lucy method: both the Split Bregman and Wiener methods give poor results around
stars because of the extreme dynamic range. For linear images it is usually best to use the gradient descent Richardson-
Lucy methods, and if ringing occurs around bright stars then reduce the step size. This approach reduces the impact

8.3. Filters 163

Siril, Release 1.2.0

of each iteration therefore more iterations are required, but it does mean that you can achieve finer control taking
deconvolution just up to the point where artefacts start to form and then backing off very slightly. For stretched images
the multiplicative Richardson-Lucy algorithms may be used.

Tip: For stacked lunar and planetary images the Split Bregman or Wiener methods can be more appropriate. These
methods do not generally require iteration in the way that Richardson-Lucy does, and they may be better suited to the
noise characteristics of stacked, high signal-to-noise ration images. (The Richardson-Lucy algorithm is based on an
assumption of Poisson noise, which is usually true for DSO imaging, whereas the Wiener method implemented here
assumes a Gaussian noise distribution which may fit stacked planetary / lunar images better).

Parameters and Settings

General Settings

• PSF size. The input PSF size should be chosen sufficiently large to assure that the PSF is included in the specified
domain. However, setting it too large can result in a poorer and more time-consuming result from the blind PSF
estimation methods.
• Lambda (𝜆). Regularization parameter for PSF estimation. Try decreasing this value for noisy images.

0 descent PSF estimation settings

• Multiscale. This setting enables multiscale PSF estimation. This may help to stabilize the PSF estimaate when
specifying a large PSF size, but some PSFs generated with this option can give rise to unnatural looking results
and it is therefore off by default.
• Expert settings. These should not normally require adjustment, but are made available for the curious.
– Gamma sets the regularization strength used when carrying out the sharp image prediction step. For a
given gamma, as the noise increases the estimation also gets noisier. If gamma is increased, the estimation
is less affected by noise but tends to be smoother. The default value of 20 was determined experimentally
in [Anger2019].
– Iterations sets the number of iterations used in the PSF estimate procedure. The authors of the algorithm
report that there is minimal benefit in increasing this to 3 and no benefit at all in increasing it beyond 3.
– Lambda ratio and lambda minimum sets the parameters for refining the sharp image prediction through
successive values of the sharp image predictor regularization parameter at each iteration of the method.
– Scale factor, upscale blur and downscale blur are only used when multiscale estimation is active. These set
the default scale factor between each scale level and the amount of blurring to use when rescaling between
each scale.
– Kernel threshold. Values below this level in the PSF estimate are set to zero.

164 Chapter 8. Processing

 Siril, Release 1.2.0

Spectral Irregularity PSF estimation settings

• Compensation factor controls the strength of a filter used to avoid excessive sharpness in the estimated PSF. For
images with intrinsic blur, a value close to unity should be used. For intrinsically sharp images, low values can
result in artefacts and the value should be increased to a large number, effectively disabling the filter.
• Expert settings. These should not normally require adjustment, but are made available for the curious.
– Inner loop iterations sets the number of iterations performed in the inner loop of the spectral irregularity
method. The algorithm converges quickly and it may be possible to reduce this to approximately 100
without much degradation of the result.
– Samples per outer loop. This controls how many random phases should be sampled. Because the phase
retrieval starts with random values for each sample, it is important to draw enough samples to avoid con-
verging to a local minimum. The PSF stabilizes quickly for low noise images, but if looking for improved
results from this method, this is the first of the expert settings to try adjusting especially with images with
higher noise levels.
– Outer loop iterations. [Anger2018], suggests that 2 iterations can be enough to produce a plausible PSF
estimate, and there is negligible value in increasing this above 3.

PSF from Stars

• This PSF generation method has no adjustable parameters. It generates a PSF based on the average parameters
of the selected stars, using the findstar command or the Dynamic PSF dialog. The average parameters are shown
in the deconvolution dialog when this PSF generation method is selected. It is preferable for the user to actively
select the stars they wish to use for this method, to obtain the most accurate PSF. Ideally around 10 fairly bright
but not saturated stars should be selected from the central region of the image (to exclude stars that may suffer
from coma or other aberrations). However, if the user has not selected any stars, Siril will attempt to autodetect
suitable stars by running its detection routine with filters set to keep only stars with peak amplitudes between
0.07 and 0.7. This range avoids both saturated stars and those that are too faint to give an accurate solution. It
will work well in most cases but may still be affected by off-centre aberrations.
• If you select the Symmetrical PSF checkbox, the generated PSF will be circular. This will match the average
FWHM and beta of the selected stars but will not match any elongation.

Manual PSF

This PSF generation method allows specification of a custom parametric PSF.

• Profile type allows choice of PSF profile. Gaussian, Moffat, disc and Airy disc PSFs are supported.
– Gaussian and Moffat PSFs are used for matching star parameters measured from the image. They should
provide a good estimate of the total blur function being applied to the image, as stars are point sources.

Fig. 25: An example of Moffat PSF with fwhm=5", Angle=45°, Ratio=1.20, 𝛽 = 4.5 and a PSF size of 15.

– Disk PSFs are used to deconvolve images that are out of focus.
– Airy disc PSFs are used to deconvolve the diffraction that arises as a physical consequence of diffraction
by the aperture of your telescope.
• FWHM specifies the full width at half maximum of the chosen profile (for disc PSFs it simply specifies the
radius).

8.3. Filters 165

Siril, Release 1.2.0

Fig. 26: An example of Disk profile with fwhm=5" and a PSF size of 15.

Fig. 27: An example of an Airy-Disk PSF with Diameter=250mm, Focal Length=4500mm, Wavelength=525nm, Pixel
Size=2.9µm, Central Obstruction=40% and a PSF size of 41.

• Beta (𝛽) specifies the beta parameter used in the Moffat PSF profile. It is ignored for other PSF profiles.
• For Airy disc PSFs a number of parameters of your telescope and sensor are required:
– Aperture
– Focal length
– Sensor pixel size
– Central wavelength being imaged. Siril will try to extract this data from your image metadata where avail-
able, but if some parameters are missing or look unreasonable Siril will highlight them and print a warning
in the log recommending you check them. The ratio of the central obstruction is also required to generate
an accurate Airy disc. This is expressed as a percentage, i.e. the total area of the central obstruction divided
by the total area of the aperture x 100. For refractors this is zero; for other telescopes it varies: it may be
around 20% for a Newtonian reflector or as much as 40-50% for some Corrected Dall-Kirkham telescopes.
You will need to measure your instrument or consult the manufacturer's specifications.

Richardson-Lucy Deconvolution

The parameters used to configure Richardson-Lucy deconvolution in Siril are as follows:

• alpha sets the regularization strength. A smaller value of alpha gives stronger regularization and a smoother
result; a larger value reduces the regularization strength and preserves more image detail, but may result in the
amplification of noise.
• Iterations specifies the maximum number of iterations to use. In the absence of noise, a large number of iterations
will cause deconvolution to converge the estimate closer to the true image, however an excessively large number
of iterations will also magnify noise and cause ringing artefacts around stars. The default is 1 iteration: a higher
number can be set to compute multiple iterations automatically, or you can keep pressing Apply to apply one
iteration at a time until you are happy with the result. (Or go one further, decide you're no longer happy and use
Undo.)
• Stopping criterion sets a convergence criterion based on successive estimate differences. This will stop the
algorithm once convergence is within the specified limit. This is an important parameter - if you are getting
rings around stars in your fnal image, try increasing the value of the stopping criterion. This may be disabled
altogether using the check button.
• Algorithm method specifies whether to use the multiplicative implementation or the gradient descent imple-
mentation.
• Step size specifies the step size to use for the gradient descent implementation. Do not set it too large or the
algorithm will not converge. This parameter has no effect if the multiplicative implementation is selected.

Tip: For linear images, try using the gradient descent methods provide the control necessary to prevent ringing

166 Chapter 8. Processing

 Siril, Release 1.2.0

around stars. For deconvolving stretched images, however, this can be unnecessarily slow, so using the multi-
plicative methods can often save time without compromising image quality.

Split Bregman Deconvolution

The parameters used to configure Split Bregman deconvolution in Siril are as follows:
• alpha sets the regularization strength. A smaller value of alpha gives stronger regularization and a smoother
result; a larger value reduces the regularization strength and preserves more image detail, but may result in the
amplification of noise.
• Iterations specifies the maximum number of iterations to use. The Split Bregman method does not require
multiple iterations in the form implemented here, but may be iterated if desired. This generally makes only a
small difference and therefore defaults to 1.

Wiener Deconvolution

Wiener deconvolution in Siril only requires one parameter:

• alpha sets the regularization strength. A smaller value of alpha gives stronger regularization and a smoother
result; a larger value reduces the regularization strength and preserves more image detail, but may result in the
amplification of noise.

FFTW Performance Settings

The PSF estimation and deconvolution algorithms make extensive use of fast Fourier transforms using the FFTW li-
brary. This offers a number of tuning options, which can be adjusted in the performance tab of the main Siril preferences
dialog.

Note on Image Row Order

Different types of image processed by Siril can have their pixel data arranged in different orders. SER video files
always store data top down, whereas FITS files may store data either bottom up or top down. Bottom up is the original
recommendation, however increasingly FITS are sourced from CMOS cameras which tend to follow a top down pixel
order.
When an image is deconvolved with a PSF created from the same image (or with it open) this causes no problem.
However there is potential for problems to arise if a PSF is generated with an image with one row order and used to
deconvolve an image or sequence with the opposite row order. This is a niche use case, but handling it consistently
results in behaviour which at first sight can be surprising: it is therefore explained below.
Siril handles the issue by tracking the row order of the image the PSF was created with. PSFs are always saved using
a bottom up row order (automatically flipping them if they were created with a top down image), and when loaded the
row order is matched to the row order of the currently open image. If an image of the opposite row order is opened, the
row order of the PSF will be changed to match. This means that if, for example, you take some bottom up FITS images,
use one of them to generate a PSF, and then convert them to a top down SER sequence, the PSF will be converted to
the correct orientation to match the SER sequence. If a PSF is being previewed at the time an image with the opposite
row order is opened the preview will not update immediately: the row order change will be detected automatically and
the PSF flipped at the time when it is applied to the image.

8.3. Filters 167

Siril, Release 1.2.0

Rogues' Gallery

This section shows some examples of where deconvolution has gone wrong, together with explanations of why.

Fig. 28: The manually specified PSF was too big, resulting in large dark rings around stars.

Deconvolution: Usage Tips

You've arrived here from the hints button in the deconvolution tool in Siril. No worries: deconvolution is a tricky
technique. Even theoretically, it's really hard: there are no guarantees the maths will always converge to a unique
solution that improves your image. That said, here are some tips to help you get the most out of Siril's deconvolution
algorithms.

What PSF to use?

Using an accurate PSF is fundamental to achieving good results from deconvolution. The two simplest ways to generate
a PSF are to use a blind PSF estimate, or to model your PSF on stars in your image.

PSF from Stars

Siril can detect and model stars in your image. See the Dynamic PSF help page for details. To get a good model for
your PSF, try selecting the Moffat star profile in Dynamic PSF. Stars are point sources so the spread function of an
average star is a good model for the blurring effects that we are trying to remove by deconvolution.

Tip: Once you have detected stars, sort them by peak amplitude (parameter "A"). Select and delete any with amplitude
greater than 0.7 or less than 0.1, and if your image contains background galaxies check that no false positives remain.
Stars in this brightness range are not saturated and not too faint to give an accurate PSF model.

168 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 29: Too many iterations have been applied. (I applied them one at a time to exaggerate the result, which is why
the iterations parameter still says 1.)

Tip: If the blind generation of a deconvolution PSF can be done on linear and non-linear data, the use of a PSF from
star PSF can only be done on linear images. Otherwise the PSF values would not be valid.

Blind PSF Estimate

These methods can automatically estimate a PSF based on the image itself. If you have no better prior knowledge of
the PSF such as stars in the image (for example, lunar imagery that contains no stars) then this may be your best option.
In most cases it is recommended to use the default 0 method: it is faster and usually gives better results.

Tip: However you are generating your PSF, check the preview to make sure that it does not look cropped. If it does,
increase the PSF size until no significant parts of the PSF are cropped.

Other PSF Generation Methods

Other PSF generation methods worthy of mention are the manual disc profile and the Airy disc. The disc profile can be
used to improve images where the focus is slightly off. Try to match the size of the disc to the size of the out-of-focus
blur. The Airy disc can be used to fix the slight blurring caused by the diffraction of the telescope tube itself.

Tip: If you have exceptional seeing (little to no atmospheric blur) deconvolving the image using an Airy disc may be
all that you need.

8.3. Filters 169

Siril, Release 1.2.0

Fig. 30: Close-up showing the effect of trying to apply too much regularization (alpha = 30) using the multiplicative
version of Richardson-Lucy. For strong regularization and / or better control over each iteration, the gradient descent
formulation is recommended.

170 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 31: Typical example of attempting to deconvolve an unstretched starfield using Split Bregman (in this case) or
Wiener filter deconvolution. Those are better for planetary / lunar / solar images; for starscapes Richardson-Lucy is
always recommended.

Deconvolving the Image

Once you've generated a PSF you're happy with, you're ready to deconvolve your image. It is important to use the right
settings to get good results.

Tip: Deconvolution is quite slow for large images. To make it quicker to find the best parameters, save your work
at this point and crop a small representative part of the image. Deconvolve this with various settings, using the Undo
button until you're happy. Then undo once more to get back to your un-cropped image, and apply the settings to the
whole image.

Images with Stars

Images containing stars, especially linear (unstretched) data, should always be deconvolved using the Richardson-Lucy
methods. Ignore Split Bregman and Wiener: those algorithms are suited to solar system images.
Deep space images pose 2 challenges with deconvolution: ringing around bright stars, and noise amplification in the
background.
To deal with rings around stars, try using the Gradient Descent method and increase the number of iterations gradually
until you start to see signs of dark rings forming around stars, then reduce the iterations just a little.

The above animation shows the effect of reducing the numebr of iterations of the multiplicative formulation of
Richardson-Lucy: it also demonstrates the finer control that can be achieved by using the gradient descent method,
at the cost of more iterations.

8.3. Filters 171

Siril, Release 1.2.0

To deal with amplification of background noise, you can try applying a little noise reduction before deconvolution. In
the Noise Reduction dialog, choose the Anscombe VST secondary denoising algorithm and leave the modulation quite
low, try around 50-60%. You just want to take the edge off the noise to allow you to push the number of iterations a
little further, not generate a completely smooth image.

Lunar Images

Typically you may wish to sharpen a lunar image after stacking. Stacked lunar images can be sharpened very nicely
using the Split Bregman or Wiener methods. My usual choice is Split Bregman. Try leaving the value of 𝛼 at the
default, and deconvolving the image using a blind estimated 0 PSF. An example of this is shown below using a freshly
stacked lunar image (i.e. no wavelet processing has been done to it). Despite the limitations of the GIF animation
format the sharpening can clearly be seen; it is also clear that the results from Split Bregman and Wiener are very
similar.

Stacked Planetary Images

A typical planetary workflow involves stacking the planetary SER video in a specialist tool such as Autostakkert! or
Astrosurface, and then sharpening the resulting image using wavelets and deconvolution. A combination of Siril's A
trous Wavelets tool and the Deconvolution tool gives excellent results as shown here. This image of Jupiter was initially
sharpened using wavelets with the first layer control set to 75, the second set to 10 and the others all left at the default.
A colour PSF was then built from 3 Airy discs calculated for the telescope and sensor used (a 6" Newtonian with a 3x
Barlow lens and an ASI462MC sensor with 2.9 micron pixels) composited using the RGB composition tool. This was
used to deconvolve the image with 6 iterations of Richardson-Lucy (here I used the multiplicative version). At each
step the image becomes sharper.

Raw stack, still blurry.

Processed with Siril wavelet decomposition, wavelet layer 1 strength 75, wavelet layer 2 strength 10.
Processed with Siril wavelets as above, and then with 6 iterations of multiplicative Richardson-Lucy deconvolution.

172 Chapter 8. Processing

 Siril, Release 1.2.0

8.3. Filters 173

Siril, Release 1.2.0

Unstacked Planetary Sequences

Tip: Warning: this method is extremely slow as it requires individual processing of typically 30,000 (or more) images
in a planetary sequence!

Some users have suggested mitigating telescope diffraction pre-stacking by deconvolving your sequence using an Airy
disc PSF. To do this with a typical one-shot colour planetary camera, the sequence has to be set to debayer on load. You
can take this one step further if you wish by generating three separate Airy discs for red, green and blue wavelengths
(typically 600nnm, 530nm and 450nm respectively). Siril cannot directly generate a colour PSF (the deconvolution
UI is busy enough!) but if you save each of the red, green and blue Airy discs separately you can combine them into
a colour PSF using the RGB composition tool. Save this, and if a colour or sequence is loaded the PSF will load in
colour and will deconvolve each colour channel using the appropriate PSF.

Stacked and sharpened without individually deconvolving frames.

Raw stack: best 30% of 91k frames individually deconvolved using Siril.
Result of sharpening the individually deconvolved stack.
In the image above a slight improvement to the shape of the edge is evident in the version that was frame-by-frame
deconvolved with an Airy disc PSF using Siril's Richardson-Lucy method prior to stacking, but care must be taken to
avoid loss of details. This process is very slow: my development machine took 4.5 hours to deconvolve each of the 91k
frames in this sequence, and the improvement may be minor if any.

174 Chapter 8. Processing

 Siril, Release 1.2.0

Commands

Siril command line

makepsf clear
makepsf load filename
makepsf save [filename]
makepsf blind [-l0] [-si] [-multiscale] [-lambda=] [-comp=] [-ks=] [-savepsf=]
makepsf stars [-sym] [-ks=] [-savepsf=]
makepsf manual { -gaussian | -moffat | -disc | -airy } [-fwhm=] [-angle=] [-ratio=] [-
˓→beta=] [-dia=] [-fl=] [-wl=] [-pixelsize=] [-obstruct=] [-ks=] [-savepsf=]

Generates a PSF for use with deconvolution, any of the three methods exposed by RL, SB or WIENER commands.
One of the following must be given as the first argument: clear (clears the existing PSF), load (loads a PSF from a
file), save (saves the current PSF), blind (blind estimate of tke PSF), stars (generates a PSF based on measured stars
from the image) or manual (generates a PSF manually based on a function and parameters).

No additional arguments are required when using the clear argument.

To load a previously saved PSF the load argument requires the PSF filename as a second argument. This may be in
any format that Siril has been compiled with support for, but it must be square and should ideally be odd.

To save a previously generated PSF the argument save is used. Optionally, a filename may be provided (this must
have one of the extensions ".fit", ".fits", ".fts" or ".tif") but if none is provided the PSF will be named based on the
name of the open file or sequence.

For blind, the following optional arguments may be provided: -l0 uses the l0 descent method, -si uses the spectral
irregularity method, -multiscale configures the l0 method to do a multi-scale PSF estimate, -lambda= provides the
regularization constant.

For PSF from detected stars the only optional parameter is -sym, which configures the PSF to be symmetric.

For a manual PSF, one of -gaussian, -moffat, -disc or -airy can be provided to specify the PSF function, Gaussian
by default. For Gaussian or Moffat PSFs the optional arguments -fwhm=, -angle= and -ratio= may be provided. For
Moffat PSFs the optional argument -beta= may also be provided. If these values are omitted, they default to the same

8.3. Filters 175

Siril, Release 1.2.0

values as in the deconvolution dialog. For disc PSFs only the argument -fwhm= is required, which for this function is
used to set the diameter of the PSF. For Airy PSFs the following arguments may be provided: -dia= (sets the
telescope diameter), -fl= (sets the telescope focal length), -wl= (sets the wavelength to calculate the Airy diffraction
pattern for), -pixelsize= (sets the sensor pixel size), -obstruct= (sets the central obstruction as a percentage of the
overall aperture area). If these parameters are not provided, wavelength will default to 525nm and central obstruction
will default to 0%. Siril will attempt to read the others from the open image, but some imaging software may not
provide all of them in which case you will get bad results, and note the metadata may not be populated for SER format
videos. You will learn from experience which are safe to omit for your particular imaging setup.

For any of the above PSF generation options the optional argument -ks= may be provided to set the PSF dimension,
and the optional argument -savepsf=filename may be used to save the generated PSF: a filename must be provided
and the same filename extension requirements apply as for makepsf save filename

Links: psf , rl, sb, wiener

Siril command line

rl [-loadpsf=] [-alpha=] [-iters=] [-stop=] [-gdstep=] [-tv] [-fh] [-mul]

Restores an image using the Richardson-Lucy method.

Optionally, a PSF may be loaded using the argument -loadpsf=filename (created with MAKEPSF).

The number of iterations is provide by -iters (the default is 10).

The type of regularization can be set with -tv for Total Variation, or -fh for the Frobenius norm of the Hessian matrix
(the default is none) and -alpha= provides the regularization strength (lower value = more regularization, default =
3000).

By default the gradient descent method is used with a default step size of 0.0005, however the multiplicative method
may be specified with -mul.

The stopping criterion may be activated by specifying a stopping limit with -stop=

Links: psf , makepsf

Siril command line

sb [-loadpsf=] [-alpha=] [-iters=]

Restores an image using the Split Bregman method.

Optionally, a PSF may be loaded using the argument -loadpsf=filename.

176 Chapter 8. Processing

 Siril, Release 1.2.0

The number of iterations is provide by -iters (the default is 1).

The regularization factor -alpha= provides the regularization strength (lower value = more regularization, default =
3000)

Links: psf

Siril command line

wiener [-loadpsf=] [-alpha=]

Restores an image using the Wiener deconvolution method.

Optionally, a PSF created by MAKEPSF may be loaded using the argument -loadpsf=filename.

The parameter -alpha= provides the Gaussian noise modelled regularization factor

Links: psf , makepsf

References

8.3.6 Fourrier Transform

A Fourier transform (FT) is a mathematical transform that decomposes functions into frequency components, which
are represented by the output of the transform as a function of frequency. This transformation is widely used in imaging
because it allows to see signals at regular frequencies.
Siril allows to transform an image in the frequency space thanks to a Fast Fourier Transform algorithm. The result is
in the form of two images. The first one, automatically loaded, contains the magnitude (or modulus) of the transform,
the second one contains the phase. The location of the two images must be entered in the Direct Transform tab
(see illustration below) of the dialog. It is then possible to modify the modulus image by removing frequency peaks
corresponding to unwanted signals. It is important not to forget to save the changes.
The Centered option, when checked, centers the origin of the Direct Fourier Transform. If not, the origin is at the
top-left corner.
To reconstruct the image, click on the Inverse Transform tab and enter the filepath of the modulus and phase images.

Siril command line

fftd modulus phase

8.3. Filters 177

Siril, Release 1.2.0

Fig. 32: Direct Transform tab.

Fig. 33: Inverse Transform tab.

178 Chapter 8. Processing

 Siril, Release 1.2.0

Applies a Fast Fourier Transform to the loaded image. modulus and phase given in argument are the names of the
saved in FITS files

Siril command line

ffti modulus phase

Retrieves corrected image applying an inverse transformation. The modulus and phase arguments are the input file
names, the result will be the new loaded image

8.3.7 Median Filter

The median represents the middle data point that half of data is smaller and half of data larger than this point. This is a
robust estimator to remove outliers from a data set. Consequently, this tool can be useful as a naive denoiser, effective
against impulse noise.

Fig. 34: Median dialog window.

The layout of the window dialog is quite simple and few settings are available.
• Kernel size: From 3 × 3 to 15 × 15, this defines the size of a squared kernel that is used to apply the filter. The
larger the kernel, the more blurred the result will be.
• Iterations: This defines the number of passes of the kernel.
• Modulation: In Siril, modulation is a parameter between 0 and 1 mixing the original and processed images. A
value of 1 keeps only the processed image, a value of 0 does not apply any median filter at all.

Siril command line

8.3. Filters 179

Siril, Release 1.2.0

fmedian ksize modulation

Performs a median filter of size ksize x ksize (ksize MUST be odd) to the loaded image with a modulation parameter
modulation.

The output pixel is computed as : out=mod x m + (1 mod) x in, where m is the median-filtered pixel value. A
modulation's value of 1 will apply no modulation

8.3.8 Noise Reduction

Image Noise

Images suffer from various types of noise:

1. Impulse noise
• This type of noise (sometimes called “salt and pepper noise”) typically arises from hot or cold pixels. It
is usually dealt with by using sigma rejection stacking, but sometimes you may need to deal with it if
processing a single unstacked image.
2. Additive White Gaussian Noise
• This type of noise is typical of well-illuminated photographs: it arises from the thermal and electronic
fluctuations of the acquisition device, and the noise level is independent of the signal. AWGN can be
reduced at capture time by using cooled cameras, and it is reduced in stacking because stacking 𝑛 images
increases the correlated signal by a factor of 𝑛 whereas the uncorrelated noise only increases by a factor of
√
𝑛. It is also the type of noise that most classical denoising algorithms are designed to remove.
3. Poisson Noise
• When dealing with photon-starved images, the character of the noise ceases to be primarily Gaussian and
the probabilistic nature of photon counting becomes significant or even dominant. This is modelled by a
Poisson distribution and this type of noise is signal dependent.

Noise Reduction in Siril

Siril provides well-studied state-of-the-art classical denoising algorithms. The criteria for choosing algorithms were:
• The algorithm should be analysed in peer reviewed academic journals, with a description of the algorithm and
an objective quantitative comparison of its performance.
• The authors should have made available a F/OSS implementation. This is important to avoid IP issues and, where
the reference implementations have been used directly, to ensure licence compatibility.
• The algorithms should perform at a reasonable speed.
• Finally, the implementation of the algorithm must be capable of processing 32 bit floating point pixel data.
Neural network denoising technology was investigated, but discounted at the current time on the grounds of develop-
ment complexity. The denoising performance of neural networks can typically beat classical approaches by up to a dB
peak signal-to-noise ratio, but performance is highly dependent on the neural network being trained on data represen-
tative of the real live data.

180 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 35: Noise Reduction dialog

Algorithms: Impulse Noise

Siril primarily removes impulse noise through sigma rejection stacking. If you use this stacking method, you shouldn’t
have any issues with impulse noise. However if you are working on a single exposure you may well find impulse noise
in your image. This should be dealt with using Siril’s Cosmetic Correction function before any other noise reduction is
used, as the presence of impulse noise can skew AWGN denoising algorithms and create artefacts. It works in a similar
way to sigma rejection, but on neighbouring pixels. Any pixel whose intensity is more than n standard deviations away
from its neighbours will be rejected and replaced by a value based on the median of the neighbours. In the Denoising
tool Cosmetic Correction is active by default and will take place before any additional denoising steps. (Even if impulse
noise removal has already been carried out, leaving the setting on does no harm.) Alternatively, Cosmetic correction
can be applied manually using the Cosmetic Correction tool in the Image Processing menu.

Algorithms: Additive White Gaussian Noise

The main AWGN noise reduction algorithm used in Siril is Non-Local Bayesian (NL-Bayes) denoising [Lebrun2013].
• Non-local denoising algorithms represented a major improvement over previous pixel-centred linear filters. NL-
Bayes is an improved version of the earlier non-local denoising algorithms and offers one of the best classical
AWGN denoising algorithms. It is marginally better than the modern “benchmark” algorithm Block Matching
and 3D tranform (BM3D) noise reduction and much faster to execute.
• The key parameter required to optimise the performance of AWGN algorithms is sigma, the standard deviation of
the noise. Siril measures the noise level directly from the image data and passes this to the NL-Bayes algorithm,
therefore in the Siril denoising tool there are no configurable inputs to NL-Bayes.
Siril complements NL-Bayes with a number of other noise reduction algorithms:
• Data-Adaptive Dual Domain Denoising (DA3D) [Pierazzo2017]

8.3. Filters 181

Siril, Release 1.2.0

– This takes the output of NL-Bayes and uses it as a guide image. This guide image is used to reprocess the
original image by performing frequency domain shrinkage on shape and data-adaptive patches. It slightly
improves the performance of NL-Bayes at some additional computational cost. The shape and data-adaptive
patches are dynamically selected, thus concentrating the computations on the areas with greatest image
detail. It can also help to reduce staircase artefacts present in the guide image.
– In the Siril denoising tool, DA3D is a simple toggle with no optional settings.
• Strengthen, Operate, Subtract iteration (SOS) [Romano2015]
– SOS works by iterating the primary denoising algorithm several times. At each iteration the image is
"strengthened" by mixing in a proportion of the original noisy image. The NL-Bayes algorithm runs on
this strengthened image, after which the previous estimation is subtracted.
– The image x at an iteration 𝑘 + 1 is given by 𝑥𝑘+1 = 𝑓 (𝑦 + 𝑥𝑘 ) − 𝑥𝑘 where 𝑦 is the noisy input image.
– In the Siril denoising tool, SOS is a toggle with two parameters: the number of iterations can be set,
and the proportion of the noisy image mixed in at each iteration (rho) can be set. Avoid setting rho too
high as it can result in issues with SOS converging: the default values (3 iterations and rho = 0.2)
are usually fine.

Algorithms: Poisson and Poisson-Gaussian Noise

• Anscombe Variance-Stabilising Transform [Mäkitalo2011], [Mäkitalo2012]

– Variance stabilising transforms are used for images with Poisson or Poisson-Gaussian noise to minimise
the signal dependence of the noise and make it look more like AWGN, which NL-Bayes is good at remov-
ing, and then an inverse transform √︁
is applied on completion. The transform chosen for use in Siril is the
Anscombe transform 𝐴 : 𝑥 → 2 × 𝑥 + 38
(︀ )︀

– As the transform is non-linear, use of the direct algebraic inverse results would bias the output. Siril there-
fore uses a closed-form approximation to the exact unbiased inverse, which is quick to calculate and pro-
duces a substantial improvement over other forms of inverse such as the asymptotic inverse.
– In the Siril denoising tool, the Anscombe VST is a simple toggle with no optional settings.
Note that only one of the above mentioned complementary denoising algorithms can be chosen.
The animation below shows what is possible using variance stabilisation with a photon-starved image, in this case a
single 5 minute red filter sub of the Pelican nebula, shown with the AutoStretch screen transfer function. Note the
lack of blurring, bloating or loss of detail around stars and the sharp edge of the nebula in the bottom left part of
the image compared with what might be obtained through more basic noise reduction schemes. Once stretched more
sympathetically and combined with other channels this would greatly improve the quality achievable from very limited
data (though more data is always the better solution!)

Fig. 36: Denoising a photon-starved image

182 Chapter 8. Processing

 Siril, Release 1.2.0

Modulation

In Siril, modulation is a parameter between 0 and 1 mixing the original and denoised images. A value of 1 keeps
only the denoised image, a value of 0 does not apply any denoising at all. Modulation obviously reduces denoising
performance, but in some instances if denoising has left flat areas of the image looking a little too smooth, you can use
some modulation to restore the appearance of microtexture in these regions.

When to run Noise Reduction

The noise reduction algorithms are designed to remove AWGN and should therefore perform best on unstretched im-
ages: if white noise has a non-linear stretch applied, its characteristics change and it is no longer white. Performing
noise reduction on stretched images can still be done and will result in an improvement, but potentially will not be as
effective as if applied at the linear stage.

Noise Reduction Interface

The Siril Noise Reduction tool can be accessed in two ways: via the GUI, or via the command interface. The GUI is
shown below. Note: the SOS advanced options are hidden if SOS is not selected.

Fig. 37: Siril Noise Reduction GUI

Noise reduction can also be applied using Siril commands, either in the console or in scripts. The format is:

8.3. Filters 183

Siril, Release 1.2.0

Siril command line

denoise [-nocosmetic] [-mod=m] [ -vst | -da3d | -sos=n [-rho=r] ] [-indep]

Denoises the image using the non-local Bayesian algorithm described by Lebrun, Buades and Morel.

It is strongly recommended to apply cosmetic correction to remove salt and pepper noise before running denoise, and
by default this command will apply cosmetic correction automatically. However, if this has already been carried out
earlier in the workflow it may be disabled here using the optional command -nocosmetic.

An optional argument -mod=m may be given, where 0 <= m <= 1. The output pixel is computed as : out=m x d + (1
m) x in, where d is the denoised pixel value. A modulation value of 1 will apply no modulation. If the parameter is
omitted, it defaults to 1.

The optional argument -vst can be used to apply the generalised Anscombe variance stabilising transform prior to
NL-Bayes. This is useful with photon-starved images such as single subs, where the noise follows a Poisson or
Poisson-Gaussian distribution rather than being primarily Gaussian. It cannot be used in conjunction with DA3D or
SOS, and for denoising stacked images it is usually not beneficial.

The optional argument -da3d can be used to enable Data-Adaptive Dual Domain Denoising (DA3D) as a final stage
denoising algorithm. This uses the output of BM3D as a guide image to refine the denoising. It improves detail and
reduces staircasing artefacts.

The optional argument -sos=n can be used to enable Strengthen-Operate-Subtract (SOS) iterative denoise boosting,
with the number of iterations specified by n. In particular, this booster may produce better results if the un-boosted
NL-Bayes algorithm produces artefacts in background areas. If both -da3d and -sos=n are specified, the last to be
specified will apply.

The optional argument -rho=r may be specified, where 0 < r < 1. This is used by the SOS booster to determine the
amount of noisy image added in to the intermediate result between each iteration. If -sos=n is not specified then the
parameter is ignored.

The default is not to apply DA3D or SOS, as the improvement in denoising is usually relatively small and these
techniques requires additional processing time.

In very rare cases, blocky coloured artefacts may be found in the output when denoising colour images. The optional
argument -indep can be used to prevent this by denoising each channel separately. This is slower but will eliminate
artefacts

184 Chapter 8. Processing

 Siril, Release 1.2.0

Comparison

The images below provide a simplistic comparison of the different algorithms. Note that only one image is used: in
practice, different algorithms will be better suited for use on different images. All the images can be clicked on to view
at 100% zoom.

Original noisy image

Fig. 38: Noisy image

Denoised with NL-Bayes only

Denoised with NL-Bayes only, with 75% modulation to restore some microtexture

Denoised with NL-Bayes using the Anscombe transform

Denoised with DA3D using a NL-Bayes guide image

Denoised with NL-Bayes and SOS

Limitations

The main limitation is that the algorithms work best when the noise is Gaussian in character (or can be made approxi-
mately Gaussian using the VST). There are some reasons why this might not be true:

8.3. Filters 185

Siril, Release 1.2.0

Fig. 39: Denoised with NL-Bayes only

Fig. 40: Use of modulation

186 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 41: Denoised with NL-Bayes, variance stabilised with Anscombe transform. A 200% uninterpolated zoom is
shown to the right.

Fig. 42: Denoised with DA3D, guide image prepared using NL-Bayes. A 200% uninterpolated zoom is shown to the
right.

8.3. Filters 187

Siril, Release 1.2.0

Fig. 43: Denoised with NL-Bayes and SOS iterations. A 200% uninterpolated zoom is shown to the right.

• If the image has already been heavily processed, for example with deconvolution or wavelet sharpening, the
character of the noise will not generally be Gaussian any more. If both noise reduction and deconvolution form
part of your workflow, noise reduction should be done first.
• OSC images may denoise less well than mono or composited colour images. A small reduction of luminance
AWGN is achieved but as a result of the deBayering process the character of the noise is changed so that it is no
longer well modelled as AWGN, and is not removed very effectively. Additionally, for both OSC and composited
mono colour images, chrominance noise tends not to be well modelled as AWGN and requires different treatment.
At present chrominance noise is best tackled in general purpose image manipulation software such as The GIMP.

References

8.3.9 Rotational Gradient (Larson Sekanina Filter)

The rotational gradient, also called Larson Sekanina filter, is a filter that allows to remove circular structures from
an image, to better highlight other details. This technique is particularly effective to show the jets coming out of the
nucleus of a comet.
The principle is quite simple: this image processing consists in subtracting two copies of the image from each other,
one of the two copies having been previously rotated with respect to a point defined in the image.
• If there are circular structures around this point they are not modified by rotation and will disappear after rotation.
• If there are non-circular structures, like jets in the coma, they will be shifted in relation to each other between
the two copies and the subtraction will amplify the contrast of this structure in the result.
• If the comet moves in the image, it is possible to add a radial shift.
In the example below, concerning the comet 46-P Wirtanen, the alignment was made on the comet and the stars show
important trails. The comet is very circular and it is difficult to see details about its activity. Therefore, it is not

188 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 44: Dialog box of the Rotational Gradient filter.

necessary to define a radial shift. For the rotation, an angle of a little more than 28° was chosen (this choice was made
after several attempts and using the undo button to go back). To choose the coordinates of the center of rotation, just
make a selection around the cometary nucleus and click on Use current selection. This action will copy the coordinates
of the centroid to the desired location.
A simple click on Apply will apply the filter. In our example, the tail becomes visible.

Siril command line

rgradient xc yc dR dalpha

Creates two images, with a radial shift (dR in pixels) and a rotational shift (dalpha in degrees) with respect to the
point (xc, yc).

Between these two images, the shifts have the same amplitude, but an opposite sign. The two images are then added
to create the final image. This process is also called Larson Sekanina filter

8.3. Filters 189

Siril, Release 1.2.0

Fig. 45: Image of a comet whose tail is barely visible.

190 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 46: After applying the filter, the tail of the comet appears very clearly.

8.3. Filters 191

Siril, Release 1.2.0

8.4 Star Processing

Stars are an integral part of deep sky images and play a crucial role in bringing out the beauty and detail of celestial
objects. They often appear as brilliant dots of light, showcasing their brightness and colors, making deep sky images
truly captivating. However, due to the limitations of observing conditions, the stars in these images may appear larger
and over-exposed. To combat this, astronomers use advanced image processing techniques to separately process the
stars and control their size and brightness in the final image.
This part of the documentation is then dedicated to everything related to the stars processing.

8.4.1 StarNet Star Removal

StarNet is a software developed by Nikita Misiura. Its first version was released under a free and opensource license.
Unfortunately, version 2 became proprietary and the sources are since closed. The version 2 is available free of charge
from there. Make sure you download the Command Line Tool version. Siril can interface with any version of the
StarNet CLI tool, including the new experimental Torch-based version that has initially been released for M1- and M2-
based Apple Macs.

Warning: If you are wondering why StarNet doesn’t launch, please run it outside Siril first. It’s not Siril’s fault
if it’s not supported by your computer or badly installed for some reason. If your processor does not support the
vectorization instructions required by StarNet, there is no way to bypass that. The error message will be obtained
by executing StarNet alone.

Tip: On MacOS, for Siril to detect and use StarNet correctly, it is necessary to fix some permissions and security
issues first. Start by opening the Terminal application from the Utilities folder within Applications. In Terminal, you
need to change your working directory from your home directory to the StarNetCLI installation directory. To do this
type in cd followed by a space and then drag the StarNetCLI folder into the terminal window to copy its path. Press
enter. Then type in the following four commands, pressing enter after each one:

xattr -r -d com.apple.quarantine libtensorflow_framework.2.dylib

xattr -r -d com.apple.quarantine starnet++
chmod +x starnet++
chmod +x run_starnet.sh

Then, at the first use with Siril, the execution of StarNet may fail with a warning about libtensorflow. Cancel out of this
warning. Open System Preferences and under Privacy and Security click the Allow anyways button for libtensorflow.
After this, StarNet should execute properly in Siril.

Tip: On MacOS, again, there is a new Starnet executable optimized for the Apple Silicon chip that has been released on
the site: https://www.starnetastro.com/experimental/. This new version is much faster than previous version because
it uses the new MPS accelerated PyTorch (https://developer.apple.com/metal/pytorch/). Also, this version contains
signed binaries, follow the installation instructions in the README.txt

However, it is still possible for Siril to run external binaries and this is what we decided to implement starting with Siril
1.2.0. For the settings, please refer to the preference page. It explains how to tell Siril where StarNet is located.

192 Chapter 8. Processing

 Siril, Release 1.2.0

Warning: This is the location of the command line version of StarNet that need to be given, not the GUI one.

Note that StarNet requires its input in the form of TIFF images, therefore if Siril is compiled without libtiff support
then the StarNet integration will not be available.
The primary purpose of StarNet is to remove all the stars from the images in order to apply a different process between
the stars and the rest of the image. This usually helps to control star bloat during the different stretches, but it is also
very useful for creating images of comets where the comet tracking rate can be significantly different to the distant
stars.

Fig. 47: StarNet dialog box.

The tool is very easy to use and only five options are available:
• Pre-stretch linear image: If selected, an optimised Midtone Transfer Function (MTF) stretch is applied to the
image before running StarNet, and the inverse stretch is applied on completion. This is necessary for using
StarNet at the linear stage of processing.
• Recompose stars on completion: If selected, on completion of the star removal process the star recomposition
tool will open, providing an interface for independently stretching and blending the background and the stars if
star reduction, rather than total removal, is desired. This option has no effect when processing a sequence.
• Generate star mask: This will generate a star mask and saved it in the working directory. The star mask is
calculated as the difference between the original image and the starless image. The default is to produce a star
mask.
• Upsample x2: This option will up-sample the image by a factor of 2 before running StarNet. This improves
performance on very tight stars but quadruples processing time and may impair performance on very large stars.
The image is rescaled to the original size on completion.
• Use custom stride: A custom value may be entered for the StarNet stride parameter. The default value is 256
and the StarNet developer recommends not to change this.
The StarNet process can easily be applied to a sequence. The togglebutton Apply to sequence selects whether the
process will apply to a single image or to a sequence. Where the process is applied to a sequence, a new sequence will
be created containing the starless images and, if star mask generation is selected, a second sequence will be created
containing the corresponding star mask images.
More information about StarNet can be found on the original website.

8.4. Star Processing 193

Siril, Release 1.2.0

A click on Execute will run the process. It can be slow, depending of your machine performance. However, Siril shows
a progressbar to follow the processing. As with other Siril processes, if processing a sequence the progressbar will only
update after completion of each image in the sequence, and will show the overall progress through the sequence.

Commands

Siril command line

starnet [-stretch] [-upscale] [-stride=value] [-nostarmask]

Calls StarNet to remove stars from the loaded image.

Prerequisite: StarNet is an external program, with no affiliation with Siril, and must be installed correctly prior the
first use of this command, with the path to its CLI version installation correctly set in Preferences / Miscellaneous.

The starless image is loaded on completion, and a star mask image is created in the working directory unless the
optional parameter -nostarmask is provided.

Optionally, parameters may be passed to the command:

- The option -stretch is for use with linear images and will apply a pre-stretch before running StarNet and the inverse
stretch to the generated starless and starmask images.
- To improve star removal on images with very tight stars, the parameter -upscale may be provided. This will
upsample the image by a factor of 2 prior to StarNet processing and rescale it to the original size afterwards, at the
expense of more processing time.
- The optional parameter -stride=value may be provided, however the author of StarNet strongly recommends that the
default stride of 256 be used

Siril command line

seqstarnet sequencename [-stretch] [-upscale] [-stride=value] [-nostarmask]

This command calls Starnet++ to remove stars from the sequence sequencename. See STARNET

Links: starnet

194 Chapter 8. Processing

 Siril, Release 1.2.0

8.4.2 Star Recomposition

Star Recomposition is a GUI tool to aid in combining starless and star mask images. It doesn't provide any unique
image manipulation that can't be done in other ways, for example using PixelMath and the Generalized Hyperbolic
Stretch tool, but it does provide a real-time preview of the combination of two separate images with different stretches
applied to each.
There is no command-line equivalent for this tool as it is purely graphical in nature, however starless and star mask im-
ages could be combined using the pm and GHT-related commands (ght, invght, modasinh, invmodasinh and linstretch).
The tool is found in the Image Processing menu, in the Star Processing sub-menu.
The dialog is divided into two columns, one for each of the input images.

Fig. 48: Star Recomposition dialog box.

Each input image is loaded using the respective file chooser. Each column has a stretch histogram preview, which may
be minimized to aid use on small displays, a set of GHS stretch controls, and Reset and Apply buttons.
The histogram mode can be changed between linear and logarithmic using the toggle at the bottom of the dialog. This
dialog obeys the Siril-wide preference for linear or logarithmic histograms that can be set in the Preferences window.

8.4. Star Processing 195

Siril, Release 1.2.0

Simple Mode

The dialog has two views, which determines what controls are shown. It opens in Simple mode, which shows only the
most useful controls for a typical starless / starmask combination.
• The stretch type for the starless image is set to Generalized Hyperbolic stretch and the Stretch Factor, Local stretch
intensity, Symmetry Point and Black Point controls are shown. As well as using the SP control, the Symmetry
Point can be set using the eyedropper tool to select the average pixel value of a selection from the image. Note
that the eyedropper tool is disabled when there is an unapplied BP shift: because of the process of applying the
hyperbolic stretch and then the BP shift, the behaviour of the tool becomes non-intuitive when a non-zero BP
parameter is set. To resolve this, simply apply the BP shift and the eyedropper will become available again for
your next hyperbolic stretch.
• The stretch type for the star mask image is set to Modified Arcsinh stretch and the Stretch Factor and Highlight
Protection controls are shown.
• The human-weighted luminance color model is used for both sets of stretches: this does a better job of preserving
colors in the unstretched image.
Details of all the stretch controls, both those shown in Simple mode as well as those shown in Advanced mode, can be
found on the Generalized Hyperbolic Stretch documentation page.
The BP control works in a slightly different way to the BP control in the standalone GHS linear (black point adjust)
stretch. In this tool the Black Point adjustment is applied after the hyperbolic stretch, whereas in the standalone tool it is
a separate stretch applied by itself. When trying to optimize the combination of independent stretches to the two input
images, this was found to be the most workable approach. It does mean that the amount of black point shift required in
this tool is different to the amount required in the GHS tool, and that the Black Point cannot be set by clicking on the
histogram.
Each stretch is independent. The stretch settings for the starless side can be applied using the left-hand Apply button:
this stretches the starless image according to the current stretch settings and then resets the stretch settings so that further
stretches can be applied in an iterative manner. Similarly, the stretch settings for the star mask can be applied using the
right-hand Apply button. Either set of stretch settings can be reset to the defaults using its respective Reset button.
The dialog can be toggled between Simple and Advanced mode using the button at the bottom.

Advanced Mode

In Advanced mode the full range of GHS stretch controls are available including Stretch Type, Colour stretch model
and Shadow protection point for both input images. This allows greater customization of the two stretches if required.
If the user interface is put back to Simple mode, any changes made using the advanced controls remain in effect, only
the controls are hidden.

Note: It is not possible to stretch the saturation channels in this tool. The tool is already quite memory-hungry and CPU
intensive: doubling the memory requirement by adding a HSL copy of each working image is considered excessive.
Saturation can easily be stretched separately after the combination is complete.

196 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 49: Using Star Recomposition combine a starless image and star mask of the Alnitak region

8.4.3 Desaturate Stars

When a star finder is applied to an image (whose data are always linear), ellipses are displayed around the stars. When
an ellipse is magenta, it means that the star is saturated.
A saturated star is a star whose brightest pixels have no more information and are clipped to the maximum value. In
general we try to not to saturate the stars, even if this is not possible for the brightest. If despite the precautions there
are still saturated stars, Siril has an algorithm that will reconstruct the profile of the star taking into account the results
of the adjustment made during the findstar.

First, you need to perform a star detection, either with the findstar command or the button of the Dynamic PSF
Window. Then, the desaturate tool is found in Star Processing → Desaturate Stars.

Tip: We recommend using a Moffat profile in the Dynamic PSF window to get better parameters.

Warning: It is important to run this tool on linear images, otherwise the stars will not have a Gaussian/Moffat
profile and the calculations will be invalid.

After clicking on the tool, Siril switches to the console and displays the results of the current process:

22:26:17: Star synthesis (desaturating clipped star profiles): processing...

22:26:17: Findstar: processing for channel 0...
22:26:21: Star synthesis: desaturating stars in channel 0...
22:26:21: Star synthesis: 70 stars desaturated
(continues on next page)

8.4. Star Processing 197

Siril, Release 1.2.0

Fig. 50: A star detection shows all stars found by Siril. Magenta ellipses are for saturated stars. The image is displayed
in autostretch view: data are still linear.

198 Chapter 8. Processing

 Siril, Release 1.2.0

(continued from previous page)

22:26:21: Remapping output to floating point range 0.0 to 1.0
22:26:21: Execution time: 4.09 s

It is necessary to run a star detection again to see the changes.

Fig. 51: After a desaturate processing, no more magenta ellipses are visible. All stars have been reconstructed. The
image is displayed in autostretch view: data are still linear.

Siril command line

unclipstars

Re-profiles clipped stars of the loaded image to desaturate them, scaling the output so that all pixel values are <= 1.0

8.4. Star Processing 199

Siril, Release 1.2.0

Fig. 52: Comparison for a star before and after the application of the desaturation tool.

8.4.4 Full Resynthesis

The Full Resynthesis tool aims to help to fix badly distorted stars using Siril's star fitting functions. It can be helpful
for rescuing images that suffer from bad coma or other distortions. If Siril can detect the stars it can fix them.
The tool is located in the Image Processing menu, in the Star Processing sub-menu.
The output of the tool is a synthetic star mask. In order to make use of this, it must be recombined with a starless version
of the original image. This can be prepared using the starnet command or Starnet GUI tool, or using third party star
removal software.
This tool has no options, you simply click on the menu item to use it, or use the command synthstar.
If no stars have been detected in the image, the tool will automatically detect stars using the current star modelling
parameters accessible via the Dynamic PSF tool or using the setfindstar command.
If stars have been modelled using the Dynamic PSF tool or the findstar command, the detected stars will be resynthe-
sized using their individual modelled luminosity profiles. A shortcut to the Dynamic PSF tool is provided by means of
the configuration button in the GUI menu next to the Full Resynthesis tool.
It is recommended to carry out star detection manually first, as it allows verification of the results: if any galaxies have
been incorrectly detected as stars, they can be removed from the list of stars before running resynthesis.
Once the synthetic star mask has been created it can be combined with the starless image using the Star Recombination
tool.

200 Chapter 8. Processing

 Siril, Release 1.2.0

Commands

Siril command line

synthstar

Fixes imperfect stars from the loaded image. No matter how much coma, tracking drift or other distortion your stars
have, if Siril's star finder routine can detect it, synthstar will fix it. To use intensive care, you may wish to manually
detect all the stars you wish to fix. This can be done using the findstar console command or the Dynamic PSF dialog.
If you have not run star detection, it will be run automatically with default settings.

For best results synthstar should be run before stretching.

The output of synthstar is a fully corrected synthetic star mask comprising perfectly round star PSFs (Moffat or
Gaussian profiles depending on star saturation) computed to match the intensity, FWHM, hue and saturation
measured for each star detected in the input image. This can then be recombined with the starless image to produce an
image with perfect stars.

No parameters are required for this command

Links: psf

8.5 Geometry

8.5.1 Rotate

Rotate 90 degrees

It is possible to rotate the image 90 degrees clockwise and counterclockwise with the dedicated menu. Here the rotation
is done without interpolation of the pixels and it is therefore the preferred method if you want to rotate the image by a

multiple of 90 degrees. This feature is also reachable through the icons and in the toolbar.

Rotate&Crop

For a rotation of another angle you have to use the Rotate&Crop tool. It allows a precise rotation and cropping that can
be easily controlled.
Five interpolation algorithms are available:
• Nearest Neighbor
• Bilinear
• Bicubic
• Pixel Area Relation

8.5. Geometry 201

Siril, Release 1.2.0

Fig. 53: Rotate&Crop dialog box showing all settings.

• Lanczos-4 (Default)
Lanczos-4 is the one that gives the best results. However, if you see artifacts, especially stars surrounded by black pixels,
then you may want to try others. However, the button Interpolation clamping applies a clamping factor to Bicubic and
Lanczos-4 interpolation in order to prevent ringing artifacts.
If you don't want the image to be cropped after rotation, then you should uncheck the crop button. However, the missing
areas of the picture will be filled with black pixel.
The interest of this tool is that the rotation of the image is represented by a red frame, as illutrated in the figure below.
In addition, if a selection is active, it is possible to change its size and see in real time the framing evolve.

Siril command line

rotatePi

Rotates the loaded image of an angle of 180° around its center. This is equivalent to the command "ROTATE 180" or
"ROTATE -180"

Links: rotate

Siril command line

rotate degree [-nocrop] [-interp=] [-noclamp]

Rotates the loaded image by an angle of degree value. The option -nocrop can be added to avoid cropping to the
image size (black borders will be added).

202 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 54: Rotate&Crop dialog box with a active selection. Click to enlarge the figure and see the details better.

8.5. Geometry 203

Siril, Release 1.2.0

Note: if a selection is active, i.e. by using a command `boxselect` before `rotate`, the resulting image will be a rotated
crop. In this particular case, the option -nocrop will be ignored if passed.

The pixel interpolation method can be specified with the -interp= argument followed by one of the methods in the list
no[ne], ne[arest], cu[bic], la[nczos4], li[near], ar[ea]}. If none is passed, the transformation is forced to shift and a
pixel-wise shift is applied to each image without any interpolation.
Clamping of the bicubic and lanczos4 interpolation methods is the default, to avoid artefacts, but can be disabled with
the -noclamp argument

8.5.2 Mirror

It is also possible to apply a mirror transformation to the image. Either along the x axis or along the y axis. This

transformation is also accessible via the buttons and of the toolbar.

Siril command line

mirrorx [-bottomup]

Flips the loaded image about the horizontal axis. Option -bottomup will only flip it if it's not already bottom-up

Siril command line

mirrory

Flips the image about the vertical axis

8.5.3 Binning

The binning is a special transformation for resampling image. It computes the sum or mean of the pixels 2x2, 3x3, ...
(depending of the binning factor) of the in-memory image (like the analogic binning of CCD camera).

Siril command line

binxy coefficient [-sum]

Computes the numerical binning of the in-memory image (sum of the pixels 2x2, 3x3..., like the analogic binning of
CCD camera). If the optional argument -sum is passed, then the sum of pixels is computed, while it is the average
when no optional argument is provided

204 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 55: Binning dialog box

8.5.4 Resample

The resample tool allows to resize the image at the cost of an interpolation chosen from the following list:
• Nearest Neighbor
• Bilinear
• Bicubic
• Pixel Area Relation
• Lanczos-4 (Default)
Lanczos-4 is the one that gives the best results. However, if you see artifacts, especially stars surrounded by black pixels,
then you may want to try others. However, the button Interpolation clamping applies a clamping factor to Bicubic and
Lanczos-4 interpolation in order to prevent ringing artifacts.
If you want to change the image ratio, then you should uncheck the Preserve Aspect Ratio button.

Siril command line

resample { factor | -width= | -height= } [-interp=] [-noclamp]

Resamples the loaded image, either with a factor factor or for the target width or height provided by either of
-width= or -height=. This is generally used to resize images, a factor of 0.5 divides size by 2.
In the graphical user interface, we can see that several interpolation algorithms are proposed.

The pixel interpolation method can be specified with the -interp= argument followed by one of the methods in the list
no[ne], ne[arest], cu[bic], la[nczos4], li[near], ar[ea]}. If none is passed, the transformation is forced to shift and a
pixel-wise shift is applied to each image without any interpolation.
Clamping of the bicubic and lanczos4 interpolation methods is the default, to avoid artefacts, but can be disabled with
the -noclamp argument

8.5. Geometry 205

Siril, Release 1.2.0

Fig. 56: Resample dialog box

8.6 Background Extraction

The sky background often has an unwanted gradient caused by light pollution, the moon, or simply the orientation of
the camera relative to the ground. This function samples the background at many places of the image and looks for a
trend in the variations and removes it following a smoothed function to avoid removing nebulae with it.
Samples can be automatically placed by providing a density (Samples per line) and clicking on Generate. If areas of
the image are brighter than the median by some factor Grid tolerance times sigma, then no sample will be placed there.
After generation, samples can also be added manually (left click) or removed manually (right click).
There are two algorithms to remove the gradient:

8.6.1 RBF

This is the most modern method. It uses the radial basis function to synthesize a sky background to remove the gradient
with great flexibility. It requires a single parameter which is present in the form of a slider: Smoothing. With this value
you can determine how soft or hard the transition between the sample points is calculated. A high smoothing factor
makes sense for large and uniform gradients, and a correspondingly lower value for small, local gradations.

Tip: Start with the basic setting (50%) and gradually tweak for optimal results.

Theory
Radial basis functions are functions of the form 𝜑(x) = 𝜑(‖x‖), whereby in our case we use the Euclidean norm ‖x‖ =
𝑥21 + 𝑥22 . The function 𝑓 , which describes the background model, can now be expressed as a linear combination
√︀

∑︁
𝑓 (x) = 𝑤𝑖 𝜑(‖x − xi ‖) + 𝑜
𝑖

206 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 57: Background extraction dialog box. On the left is the polynomial version, on the right RBF.

8.6. Background Extraction 207

Siril, Release 1.2.0

where 𝑤𝑖 corresponds to the weights for the different sample points and 𝑜 corresponds to a constant offset.
The requirement that the function 𝑓 should pass through the sample points results in the condition
⎛ ⎞⎛ ⎞ ⎛ ⎞
𝜑(x1 − x1 ) 𝜑(x1 − x2 ) . . . 𝜑(x1 − x𝑁 ) 1 𝑤1 𝑦1
⎜ 𝜑(x2 − x1 ) 𝜑(x2 − x2 ) . . . 𝜑(x2 − x𝑁 ) 1⎟ ⎜ 𝑤2 ⎟ ⎜ 𝑦2 ⎟
.. .. .. .. ⎟ ⎜ .. ⎟ ⎜ .. ⎟
⎜ ⎟⎜ ⎟ ⎜ ⎟
. . . . ⎟⎜ . ⎟ = ⎜ . ⎟ ,
⎜
⎜
⎜ ⎟⎜ ⎟ ⎜ ⎟
⎝𝜑(x𝑁 − x1 ) 𝜑(x𝑁 − x2 ) . . . 𝜑(x𝑁 − x𝑁 ) 1⎠ ⎝𝑤𝑁 ⎠ ⎝𝑦𝑁 ⎠
1 1 ... 1 0 𝑜 0

which can only be fulfilled if the matrix on the left-hand side is invertible. With the right choice of function 𝜑 this can
always be guaranteed [Wright2003].
In addition, the summand 𝑠 𝐼 is added to the matrix on the left-hand side, where 𝑠 is a smoothing parameter and 𝐼 is
the unit matrix. The summand causes a regularization, which results in a smoother result the larger the parameter 𝑠 is.
This parameter can be changed with the Smoothing parameter of the dialog box.
For the radial basis function, we use the thin-plate spline 𝜑(|x|) = |x|2 log(|x|).

8.6.2 Polynomial

This is the original and simplest algorithm developed in Siril. Only one parameter is used in polynomial computation:
the Degree order. The higher the degree, the more flexible the correction, but a too high degree can give strange results
like overcorrection.

Tip: A degree 1 correction can be very useful for when you want to remove the gradient on the subs.

Theory
Polynomial functions are functions of the form

𝑓 (𝑥) = 𝑎𝑛 𝑥𝑛 + 𝑎𝑛−1 𝑥𝑛−1 + · · · + 𝑎2 𝑥2 + 𝑎1 𝑥 + 𝑎0 (8.3)

In Siril, the maximum degree allowed is 𝑛 = 4 and can be modified using the Degree order drop-down menu. Beyond
this, the model is generally unstable and gives poor results.

8.6.3 General settings

• Add dither: Hit this option when color banding is produced after background extraction. Dither is an inten-
tionally applied form of noise used to randomize quantization error, preventing large-scale patterns such as color
banding in images.
• Correction:
– Subtraction: it is mainly used to correct additive effects, such as gradients caused by light pollution or by
the Moon.

208 Chapter 8. Processing

 Siril, Release 1.2.0

– Division: it is mainly used to correct multiplicative phenomena, such as vignetting or differential atmo-
spheric absorption for example. However, this kind of operation should be done by master-flat correction.
• Compute Background: This will compute the synthetic background and will apply the selected correction. The
model is always computed from the original image kept in memory allowing the user to work iteratively.
• Show original image: Keep pressing this button to see the original image.
The background gradient of pre-processed image can be complex because the gradient may have rotated with the
acquisition session. It can be difficult to completely remove it, because it’s difficult to represent it with a polynomial
function. If this is the case, you may consider removing the gradient in the subexposures: in a single image, the
background gradient is much simpler and generally follows a simple linear (degree 1) function.

Tip: Good results with the RBF algorithm generally require fewer samples than with the polynomial algorithm.

See also:
For more explanations, see the corresponding tutorial here.

Siril command line

subsky { -rbf | degree } [-dither] [-samples=20] [-tolerance=1.0] [-smooth=0.5]

Computes a synthetic background gradient using either the polynomial function model of degree degrees or the RBF
model (if -rbf is provided instead) and subtracts it from the image.
The number of samples per horizontal line and the tolerance to exclude brighter areas can be adjusted with the
optional arguments. Tolerance is in MAD units: median + tolerance * mad.
Dithering, required for low dynamic gradients, can be enabled with -dither.
For RBF, the additional smoothing parameter is also available

Siril command line

seqsubsky sequencename { -rbf | degree } [-nodither] [-samples=20] [-tolerance=1.0] [-

˓→smooth=0.5] [-prefix=]

Same command as SUBSKY but for the sequence sequencename.

Dithering, required for low dynamic gradients, can be disabled with -nodither.

The output sequence name starts with the prefix "bkg_" unless otherwise specified with -prefix= option. Only
selected images in the sequence are processed

Links: subsky

8.6. Background Extraction 209

Siril, Release 1.2.0

8.7 Extraction

8.7.1 Split Channels

This function creates three monochrome images from a 3-channel color image, depending on the configured color
space. For RGB, it’s simply splitting the file in three. For the others, it involves computation of the equivalent color
space, either HSL (hue-saturation-lightness), HSV (hue-saturation-value) see , or CIELAB.

Fig. 58: Split channels dialog box.

Tip: If no name is given to a channel, then the channel is not extracted.

Siril command line

split file1 file2 file3 [-hsl | -hsv | -lab]

Splits the loaded color image into three distinct files (one for each color) and saves them in file1.fit, file2.fit and
file3.fit files. A last argument can optionally be supplied, -hsl, -hsv or lab to perform an HSL, HSV or CieLAB
extraction. If no option are provided, the extraction is of RGB type, meaning no conversion is done

210 Chapter 8. Processing

 Siril, Release 1.2.0

8.7.2 Split CFA Channels

CFA means color filter array. This term is often used to describe one-channel image content of a color image, with each
pixel corresponding to values acquired behind an on-sensor filter. This is to oppose to debayer images (or debayered
or demosaiced).
Opening a CFA image in Siril is required for pre-processing, like removing the dark signal before interpolating the
image into 3-channel color. We can also use the color filter information to extract images like this:
• Split CFA Channels: four images are created from the CFA image, each representing one filter of the Bayer
matrix, so in general R.fit, G1.fit, G2.fit and B.fit. It is useful if the goal is to process separately the different
colors of the image.
• Extract Ha: using an H-alpha filter with a color camera image (OSC: on-sensor color, or one-shot color camera)
means that only the pixels with red filters will be useful, so in general only a quarter of them. This function creates
a new image that contains only the pixels associated with the red filter documented in the Bayer matrix of the
image.
• Extract Ha/OIII: for OSC cameras, filters that let through photons from H-alpha and O-III wavelength have
appeared. This extraction creates two images: an image from the red pixels like the Extract Ha, and an image
combining the green and blue pixels into one for O-III. Both images are half the definition of the input image.

Note: There is a frequently asked question about why Ha and OIII images are different sizes and how they are
split out. This note attempts to explain an answer to that FAQ.
In a colour image sensor the pixels are covered in a very fine filter matrix called a Color Filter Array (CFA) or
Bayer matrix. The arrangement of filtered pixels is one of a number of patterns: RGGB, GBGR etc.

Fig. 59: Original image by Cburnett, licensed as CC BY-SA 3.0.

Of these pixels, only the R pixels are sensitive to Ha. So first we split out all the red pixels into a Ha image. As
only 1 in 4 of the CFA elements are red, the image dimensions of the Ha image are half that of the original sub.
The remaining pixels, G and B, are all sensitive to OIII. The sensitivity of the G filtered pixels to OIII is different
to the sensitivity of B filtered pixels to OIII, however they are imaging the same scene and evenly distributed so
the average intensity must be the same.
3 × Go
Gi = Gio ×
2 × Go + Bo
3 × Bo
Bi = Bio ×
2 × Go + Bo
Where Bi is the 𝑖th blue pixel, Bio is the 𝑖th original blue pixel and Bo is the average of all the original blue pixels
(and similarly for the green pixels).
So far we have an equalised set of G and B pixels with gaps where the R pixels have been removed. So finally
we use bilinear interpolation to estimate the R pixel values and end up with a full size OIII image.

8.7. Extraction 211

Siril, Release 1.2.0

Note: The Ha/OIII resampling option is how to handle the output of Extract Ha/OIII. No resampling produces
full resolution OIII image and a half resolution Ha image; upsample Ha upsamples the Ha image by a factor of 2
to match the OIII image; downsample OIII downsamples the OIII image by a factor of 2 to match the Ha image.
You may wish to use drizzling to upscale the Ha data instead of upscaling. As drizzling is a stacking method, in
this case you must use seqextract_HaOiii to extract the Ha and OIII from each frame of the sequence, and then
stack the OIII images in the usual way and the Ha images with a 2x drizzle.

• Extract Green: for photometry, it’s often useful to only process the green part of the CFA image, because it is
more sensitive and has two pixels to average, reducing noise even more. Of course, the created image also sees
its definition halved by two.

Fig. 60: Split CFA channels dialog box.

Note: These functions only work if the Bayer matrix has been properly documented by the acquisition software and
if the image format supports it, so in general FITS or SER.

Warning: This does not work with other filter matrices than the Bayer matrices, like the Fujifilm X-TRANS.

8.7.3 Wavelet Layers

This tool extracts the different planes of the image by applying the wavelet process. Each plane is saved in an image
and the set of images can be read as a sequence. You can choose up to 9 layers for the wavelet calculation and the type
of the algorithm is either Linear or BSpline. The latter is usually the preferred one.
The decomposition is done through a number of detail layers defined at increasing characteristic scales and a final
residual layer, which contains the remaining unresolved structures.

212 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 61: Wavelet Layers extraction dialog box.

8.8 Linear Match

Linear matching is the process of finding a linear function that matches best (in the sense of Least Squares) the intensity
of pixels from one image to those of a reference image. This is a quick and easy way to balance the histograms of
different images.
The Reference allows you to pick the reference image.
The Reject low and Reject high sliders allows to exclude pixels values in the left and right tails of the intensities
distributions. They are defined as quantiles, in the range [0, 1]. For instance, default for high is 0.92, meaning that the
8% brightest pixels will be excluded from the fitting to find the linear match coefficients.

Warning: The image and reference must be aligned prior to applying a linear match. Otherwise, there is no reason
to assume that their pixels intensities are correlated.

Siril command line

linear_match reference low high

Computes and applies a linear function between a reference image and the loaded image.

The algorithm will ignore all reference pixels whose values are outside of the [low, high] range

8.8. Linear Match 213

Siril, Release 1.2.0

Fig. 62: Original image of M45 (courtesy of V. Cohas).

214 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 63: 6 extracted planes.

Fig. 64: Linear match dialog

8.8. Linear Match 215

Siril, Release 1.2.0

8.9 RGB compositing

The RGB composition tool allows you to assemble up to 8 monochrome images to form a single color image. The
images can be shifted by translation but not by rotation, otherwise it will not be possible to register them. In such a
situation, it is necessary to create a mini sequence of the input images and register them with the global registration
algorithm.
The operation of this tool is quite simple, just load the images and assign them a color. The first field, optional, is
reserved for the luminance layer. Once a luminance layer is loaded you can integrate it or not in the composition thans
to the Use Luminance button. Each color can be customized by clicking on it and choosing a new one. When more
than 3 images (or 4 if there is luminance) are loaded, it may be necessary to adjust the brightness of each channel. The
Adjust layers brightness button performs this operation automatically.

Note: For binning and image dimensions, the first loaded image determines the size of the output image. If you have
images of different sizes, you should always load the largest first. If your images are different just because of bining,
so with the same field of view, the composition tool will upscale the smaller images when they are loaded to match
the size of the first loaded image. It is useful for the common L-RGB taken with the colour filters in bin 2. This also
means that if two images have not been taken with the same sensor, it is unlikely they will have the same field of view
and pixel sampling after image resampling, and this will not work with this tool.

Three color spaces are available for rendering the composition:

216 Chapter 8. Processing

 Siril, Release 1.2.0

• HSL (for hue, saturation, lightness)

• HSV (for hue, saturation, value; also known as HSB, for hue, saturation, brightness)
• CIE L*a*b*
and are left to the choice of the user.
Once the composition is finished, it is possible to do the color balance by clicking on the button Finalize color balance:
this opens the color calibration dialog.
If the images are not aligned with each other, and they are just shifted by translation, then it is possible to align them.
Two algorithms are possible:
• One star registration (deep-sky): you have to draw a selection around a star, making sure that the selection
contains the star in all channels.
• Image pattern alignment (planetary/deepsky): you have to draw a selection around the object you want to
align. A high enough contrast is required for the algorithm to work properly.

Siril command line

rgbcomp red green blue [-out=result_filename]

rgbcomp -lum=image { rgb_image | red green blue } [-out=result_filename]

Creates an RGB composition using three independent images, or an LRGB composition using the optional luminance
image and three monochrome images or a color image. Result image is called composed_rgb.fit or composed_lrgb.fit
unless another name is provided in the optional argument

8.10 Merge CFA Channels

The purpose of this tool is to combine multiple monochrome images that have been previously extracted from a CFA
sensor (with the Extraction → Split CFA channels... menu for example). The tool merges the separate red, green (x2),
and blue channel images into a single composite image called CFA image.

Warning: This tool is dedicated to images from a Bayer matrix and therefore it cannot work with images from
X-Trans files from Fuji cameras.

The dialog is split in three different parts:

• Input files: Select the image containing the CFA0, CFA1, CFA2 and CFA3 Bayer subpatterns. If this has been
produced using Siril's Split CFA function it will have the CFA prefix.
• Bayer Pattern: Sets the Bayer pattern header to be applied to the result. This must match the Bayer pattern of
the image that the original Bayer subchannels were split from.
• The sequence part, at the bottom, allows to process whole sequences by reconstituting a CFA image sequence.
Clicking on the Apply to sequence button displays a help text to proceed correctly. This text is reported in the
next tooltip. There are two available options:
– Sequence input marker: Identifier prefix used to denote CFA number in the separate CFA channel images.
This should be set to whatever sequence prefix was used when the split_cfa process was run (default: CFA_).

8.10. Merge CFA Channels 217

Siril, Release 1.2.0

– Sequence output prefix: Prefix of the image names resulting from the merge CFA process. By default it
is mCFA_.

Tip: You must have the CFA0 sequence selected in the main window sequence tab.
Your separate sub-CFA sequences must have been processed in exactly the same way.
The filenames must be in the same directory and must differ only by the name of the CFA channel. i.e. if
a CFA0 image is r_pp_CFA_0_Light_0001.fit, the corresponding images for the other CFA channels must be
r_pp_CFA_1_Light_0001.fit, r_pp_CFA_2_Light_0001.fit and r_pp_CFA_3_Light_0001.fit.
Each image in the sequence will only be processed if the corresponding images for the other 3 CFA channels
can be found. Both G1 and G2 are required. Note this means that if you discard an image containing one CFA
channel of an image between split_cfa and merge_cfa, merge_cfa will be unable to merge the remaining CFA
channels for that image. All sequence filtering should be done either before split_cfa or after merge_cfa.

Siril command line

merge_cfa file_CFA0 file_CFA1 file_CFA2 file_CFA3 bayerpattern

Builds a Bayer masked colour image from 4 separate images containing the data from Bayer subchannels CFA0,
CFA1, CFA2 and CFA3. (The corresponding command to split the CFA pattern into subchannels is split_cfa.) This
function can be used as part of a workflow applying some processing to the individual Bayer subchannels prior to

218 Chapter 8. Processing

 Siril, Release 1.2.0

demosaicing. The fifth parameter bayerpattern specifies the Bayer matrix pattern to recreate: bayerpattern should
be one of 'RGGB', 'BGGR', 'GRBG' or 'GBRG'

Siril command line

seqmerge_cfa sequencename bayerpattern [-prefixin=] [-prefixout=]

Same command as MERGE_CFA but for the sequence sequencename.

The Bayer pattern to be reconstructed must be provided as the second argment as one of RGGB, BGGR, GBRG or
GRBG.

The input filenames contain the identifying prefix "CFA_" and a number unless otherwise specified with -prefixin=
option.

Note: all 4 sets of input files must be present and must be consistently named, the only difference being the number
after the identifying prefix.

The output sequence name starts with the prefix "mCFA_" and a number unless otherwise specified with -prefixout=
option

Links: merge_cfa

8.11 Pixel Math

One of the most powerful tools in Siril is the Pixel Math. It allows you to manipulate the pixels of the images using
mathematical functions. From simple addition or subtraction, to more advanced functions, like MTF, Pixel Math is a
perfect tool for astronomical image processing.
This page aims to describe the tool entirely, to see detailed examples, please refer to the excellent tutorial on the site.
The window is divided into 5 parts.
1. The first one, including 3 text zones receiving the mathematical formulas. Only the first one is used if you want
to produce a monochrome image. Uncheck the Use single RGB/K expression button to produce RGB output.
2. The second is the variables area with the selection of Functions and Operators. Each variable is an image that
must be loaded beforehand with the + button. You can click on the desired function and/or operator to make it
appear in the formula entry to make it appear in the formula entry.
3. The third, the parameters field, allows the user to define parameters that are separated by ,. For example, if you
set parameters with the expression factor=0.8, K=0.2, all the occurences of factor and K in the formula
above will be replaced by 0.8 and 0.2 respectively. Ha * factor + OIII * K would therefore evaluate to Ha
* 0.8 + OIII * 0.2.
4. The output field is reserved for scaling the image within a given range. One need to expand the frame before
using it.

8.11. Pixel Math 219

Siril, Release 1.2.0

Fig. 65: Pixel Math dialog box as shown at opening

Fig. 66: Pixel Math parameters box

220 Chapter 8. Processing

 Siril, Release 1.2.0

Pixel Math rescale box

5. Finally, the presets area allows the user to reuse previously saved formulas with the button to the right of the
formula areas. One need to expand the frame before using it. Double-click on the formula to copy it to the right
entry.

Fig. 67: Pixel Math presets

8.11.1 Usage

Name of variables

By default it is possible to load 10 images simultaneously. Each image is given a variable name starting with I followed
by a number from 1 to 10. However, if the loaded image contains the keyword FILTER, then the value of the latter
becomes the default variable name. Of course it is always possible to change it by double clicking on it.

Fig. 68: It is possible to change the name of the variable.

Examples

Let's take a monochrome image of galaxies This is a linear data seen through the autostretch view.
The following expression:

iif(Image>med(Image)+3*noise(Image), 1, 0)

will produce a star mask.

Siril command line

pm "expression" [-rescale [low] [high]]

This command evaluates the expression given in argument as in PixelMath tool. The full expression must be between
double quotes and variables (that are image names, without extension, located in the working directory in that case)
must be surrounded by the token $, e.g. "$image1$ * 0.5 + $image2$ * 0.5". A maximum of 10 images can be used in
the expression.
Image can be rescaled with the option -rescale followed by low and high values in the range [0, 1]. If no low and high
values are provided, default values are set to 0 and 1

8.11. Pixel Math 221

Siril, Release 1.2.0

Fig. 69: Original image.

222 Chapter 8. Processing

 Siril, Release 1.2.0

Fig. 70: After the formula above.

8.11. Pixel Math 223

Siril, Release 1.2.0

8.11.2 Functions

There are two types of functions. Those that apply directly to the pixels and those that apply to the entire image (such
as the statistics functions).

Table 1: Pixel oriented functions

Func- Use case Definition
tion
abs abs ( x ) Absolute value of x.
acos acos ( x ) Arc cosine of x.
acosh acosh ( x ) Hyperbolic arc cosine of x.
asin asin ( x ) Arc sine of x.
asinh asinh ( x ) Hyperbolic arc sine of x.
atan atan ( x ) Arc tangent of x.
atan2 atan2 ( y, x ) Arc tangent of y/x.
atanh atanh ( x ) Hyperbolic arc tangent of x.
ceil ceil ( x ) Round x upwards to the nearest integer.
cos cos ( x ) Cosine of x.
cosh cosh ( x ) Hyperbolic cosine of x.
e e The constant e=2.718282...
exp exp ( x ) Exponential function.
fac fac( x ) Factorial function.
iif iif( cond, expr_true, expr_false )
Conditional function (or inline if function).
Returns expr_true if cond evaluates to nonzero.
Returns expr_false if cond evaluates to zero.

floor floor ( x ) Highest integer less than or equal to x.

ln ln ( x ) Natural logarithm of x.
log log ( x ) Base-10 logarithm of x.
log10 log10 ( x ) Base-10 logarithm of x.
log2 log2 ( x ) Base-2 logarithm of x.
max max ( x, y ) Maximum function.
min min ( x, y ) Minimum function.
mtf mtf ( m, x ) Midtones Transfer Function (MTF) of x for a midtones balance
parameter m in the [0, 1] range.
ncr ncr ( x, y ) Combinations function.
npr npr ( x, y ) Permutations function.
pi pi The constant =3.141592...
pow pow ( x, y ) Exponentiation function.
sign sign ( x )
Sign of x:
+1 if 𝑥 > 0
1 if 𝑥 < 0
0 if 𝑥 = 0.

sin sin ( x ) Sine of x.

sinh sinh ( x ) Hyperbolic sine of x.
continues on next page

224 Chapter 8. Processing

 Siril, Release 1.2.0

Table 1 – continued from previous page

Func- Use case Definition
tion
sqrt sqrt ( x ) Square root of x.
tan tan ( x ) Tangent of x.
tanh tanh ( x ) Hyperbolic tangent of x.
trunc trunc ( x ) Truncated integer part of x.

Table 2: Statistics functions

Func- Use case Definition
tion
adev adev ( Image ) Average absolute deviation of the image.
bwmv bwmv ( Image ) Biweight midvariance of the image.
height height ( Image ) Height in pixels of the specified image.
mad mad ( Image ) Median absolute deviation of the image. The use of mdev is also possible.
max max ( Image ) Pixel maximum of the image.
mean mean ( Image ) Mean of the image.
med med ( Image ) Median of the image. The use of median is also possible.
min min ( Image ) Pixel minimum of the image.
noise noise ( Image ) Estimation of Gaussian noise in the image.
sdev sdev ( Image ) Standard deviation of the image.
width width ( Image ) Width in pixels of the specified image.

8.11.3 Operators

Table 3: Operators
Opera- Use case Definition
tor
~ ~x Pixel Inversion operator.
- -x Unary Minus operator (sign change).
+ +x Unary Plus operator.
! !x Logical NOT operator.
^ x^y Exponentiation operator.
* x*y Multiplication operator.
/ x/y Division operator.
% x%y Modulus operator.
+ x+y Addition operator.
- x-y Subtraction operator.
< x<y Less Than relational operator.
<= x <= y Less Than Or Equal relational operator.
> x>y Greater Than relational operator.
>= x >= y Greater Than Or Equal relational operator.
== x == y Equal To relational operator.
!= x != y Not Equal To relational operator.
&& x && y Logical AND operator.
|| x || y Logical OR operator.

8.11. Pixel Math 225

Siril, Release 1.2.0

226 Chapter 8. Processing

 CHAPTER

NINE

PLOTTING FEATURE

Siril has a tab for displaying graphs of the data calculated during alignment or other calculations. This tab is very
powerful and allows for easy sorting of the images as well as in-depth analysis of them. The shortcut to access this tab
is F5.

9.1 Registration Plot

In order to improve manual sorting of your registered frames, plotting capabilities have been added in the Plot tab.
After completing Registration of your sequence (or when loading a registered sequence), a dropdown list now enables
to select parameters of interest for both plotting and sorting your data.
You can also choose to plot one of the parameter vs another. Items available in the dropdown list are:
• FWHM: This is the maximum width at half maximum, one of the most common criteria to judge the quality of
a deep sky image.
FWHMy
• Roundness: The roundness r is computed as the ratio of FWHMx .

• wFWHM: This is an improvement of a simple FWHM. The FWHM is weighted by the number of stars in the
image. For the same FWHM measurement, an image with more stars will have a better wFWHM than an image
with fewer stars. It allows to exclude much more spurious images by using the number of stars detected compared
to the reference image.
• Background: Average sky background value.
• # Stars: This is the number of stars used for registration.
• X Position: X-shift with regards to the reference.
• Y Position: Y-shift with regards to the reference.
• Quality: This criterion is a number in the range [0, 1] that defines the quality of images that have been processed
by any planetary registration algorithm.
Click on one of the data point to exclude the frame or to open it. The later option will load the picture and pop out the
frame selector. The parameter chosen for Y values is reflected in the frame selector last column, which can then be
used to sort, review and select or unselect subs from the sequence.
You can also mass select/unselect mutliple data points by drawing a selection onto the plot. The information at the
top of the selection tells the number of points selected, as well as the boundary values of your selection. You can
reshape the selection just as you would do with a drawn selection in the Image view. Once happy with your selection,
a right-click will display a menu to keep or exclude the points, or to set the zoom to the selection.

227
Siril, Release 1.2.0

Fig. 1: Plot tab as shown after a global registration.

228 Chapter 9. Plotting Feature

 Siril, Release 1.2.0

Fig. 2: The values of roundness vs FWHM are displayed as a scatter plot. Hover onto the different data points to show
X and Y values, together with the corresponding frame number.

9.1. Registration Plot 229

Siril, Release 1.2.0

Fig. 3: Different possibility of graphics taken with the same set of images.

Fig. 4: Right-click on a data point to exclude or to load it in the Image preview

230 Chapter 9. Plotting Feature

 Siril, Release 1.2.0

Fig. 5: Right-click on a drawn selection to mass select/unselect or to zoom

9.1. Registration Plot 231

Siril, Release 1.2.0

9.2 Photometry Plot

To complement sorting and filtering frames from the sequence, you can also perform a PSF on a star for the full
sequence. The procedure is detailed in the photometry page. Then the photometry item in the first dropdown list
becomes sensitive and is automatically selected. The other dropdown list contain the following items:
• FWHM: Maximum width at half maximum, as defined above.
FWHMy
• Roundness: The roundness r is computed as the ratio of FWHMx .

• Amplitude: It is the maximum value of the fitted function, located at the centroid coordinates.
• Magnitude: Relative magnitude of the analyzed star.
• Background: Average of the local sky background value taken in the annulus.
• X Position: X-shift with regards to the reference.
• Y Position: Y-shift with regards to the reference.
• SNR: An estimator of the signal-to-noise ratio.
In photometry, unlike registration, it is not possible to change the X axis. And only the number of images can be used
(or the Julian day).
• The Clear all and Clear latest buttons allow you to erase either all the photometric curves or the last one drawn.
• More information about NINA exoplanet can be found in the Light Curve page.

9.3 Shared options

• Each plot can be saved in png format by clicking on the Save Plot button. The file, whose name includes a
timestamp, is saved in the working directory.
• The Export to CSV button exports the displayed plot to a CSV file.
• If the sampling of the images is known, then the arcsec button displays the FWHM in arcsec instead of pixel.

Tip: Hover the word "legend" will show the legend of the plot.
• Purple curve: actual plot as configured with X and Y selectors.
• Green curve: sorted values by order of decreasing quality.
• Circle marker: the value for the reference frame.
• Cross marker: the value for the currently loaded frame.

9.4 Plot interactions

Here is a summary of the possible interactions with the plot window:

• Left-click in a slider : puts the nearest red dot on it
• Double-click in a slider : resets this axis
• Right-click + drag in a slider : move the zoom on this axis
• Left-click + drag in the plot area : draws a selection

232 Chapter 9. Plotting Feature

 Siril, Release 1.2.0

• Left-click + drag on a selection edge : resize the selection

• Double-click in the plot area : reset the zoom on the 2 axes
• Right-click when a selection is active : display the menu to : zoom on the selection/ keep only the points of the
selection/ exclude the points of the selection
• Left-click when a selection is active : delete the selection

9.4. Plot interactions 233

Siril, Release 1.2.0

234 Chapter 9. Plotting Feature

 CHAPTER

TEN

DYNAMIC PSF

This section describes the two essential steps which are undertaken to detect stars in individual frames. The detection
on a single image can be run or fine-tuned using Burger Menu → Image Information → Dynamic PSF or with shortcut
Ctrl + F6.

Fig. 1: Dynamic PSF running on a deep sky image.

The process is as follows:

• make an initial detection of potential star candidates
• fit a PSF model on each candidate. Run sanity checks based on model fitting parameters to make sure this is a
star and reject non-star candidates.
At the end of this process, the result is a list of stars, with positions in the image wrt. top left corner and measured
quantities of all the stars in the list.

235
Siril, Release 1.2.0

10.1 Initial star candidates

While it may seem obvious when looking at an image where the stars are, it is a bit more difficult to translate the process
into mathemical operations and criteria. This section briefly describes the underlying algorithm. It is inspired from
DAOPHOT software manual [Stetson1987], with simplifications brought to boost performance. The original algorithm
was aiming at being extensive in detecting all possible stars, serving the purpose of building star catalogues, while Siril
needs to detect stars primarily as features for registration . It also needs to be resilient to the wide variety of images
that are submitted - most of us do not have a professional-grade astronomical gear in the backyard - and we have had
to make some choices regarding prior knowledge of the imaging condition (sampling, seeing etc).
Over the years, our implementation has evolved to produce what it is today. It aims at not missing very bright stars,
which are important for registration, and reject as much as possible outliers, while remaining reasonnably fast at doing
so.
It can be decomposed in the following steps:
• compute the statistics of the image to capture both the background level, as the median of the image, and its
noise. This assumes that the image is relatively flat. As a consequence, detection will tend to be less efficient in
the corners if heavy vignetting is present after Calibration.
• Compute as well a dynamic range, defined as the maximum of the image minus its background. This will later
on be useful to detect saturated stars.
• smoothen the image with a gaussian kernel. Ideal smoothing would be to use the kernel that has the same FWHM
as the image. Instead, we have chosen an arbitrary size which produced satisfactory results over a very wide range
of conditions. This enables to be "blind" to the imaging parameters.
• on the smoothened version of the image, detect local maxima over a level defined as the background level plus
X times the noise (X can be varied using the threshold value in the GUI). Make sure this is a maximum over
a certain box size (defined by the radius parameter).
• run sanity check to make sure the maximum and its neighbors are well above the surrounding pixels (to reject
patches in the bright parts of nebula for instance).
• run sanity check to guess if the core around the maxima is saturated, i.e. consistently close to the upper bound
of the dynamic range. If true, run an edge-walking algorithm to detect the limit of the saturated part.
• Use first and second derivatives along an horizontal and vertical line passing through the center to guess star
local background, amplitude and width in all directions (top, down, left and right).
• If the parameters are symmetrical enough in all directions (up to the roundness parameter), confirm the star as
a potential candidate.
Once the list of potential candidates has been assembled, they are sorted by decreasing amplitudes and fed to the PSF
fitting algorithm described in the minimization section.

10.2 Models

Two models are used in the Dynamic PSF window. In general, Moffat is much better suited to fit objects such as stars.
1. An elliptical Gaussian fitting function defined as
(︂ )︂
(𝑥−𝑥0 )2 (𝑦−𝑦0 )2

𝐺(𝑥, 𝑦) = 𝐵 + 𝐴𝑒
− 2
2𝜎𝑥
+ 2
2𝜎𝑦
. (10.1)

2. An elliptical Moffat PSF fitting function defined as

)︂−𝛽
(𝑥 − 𝑥0 )2 (𝑦 − 𝑦0 )2
(︂
𝑀 (𝑥, 𝑦) = 𝐵 + 𝐴 1 + + , (10.2)
𝜎𝑥2 𝜎𝑦2

236 Chapter 10. Dynamic PSF

 Siril, Release 1.2.0

where:
• 𝐵 is the average local background.
• 𝐴 is the amplitude, which is the maximum value of the fitted PSF.
• 𝑥0 , 𝑦0 are the centroid coordinates in pixel units.
• 𝜎𝑥 , 𝜎𝑦 are the standard deviation of the Gaussian distribution on the horizontal and vertical axes, measured in
pixels.
• 𝛽 is the exponent from the Moffat formula that controls the overall shape of the fitting function. The upper bound
of this parameters was set to 10. A higher value is meaningless and means that the Gaussian is good enough to
fit the star.
Other parameters are derived from these fitted variables:
• FWHM𝑥 and FWHM𝑦 : The Full Width Half Maximum on the X and Y axis in pixel units. These parameters
are calculated as follow:
√
– FWHM𝑥 = 2𝜎𝑥 2 log 2.
√
– FWHM𝑦 = 2𝜎𝑦 2 log 2.
– It is possible to obtain the FWHM parameters in arcseconds units. This requires you fill all fields corre-
sponding to your camera and lens/telescope focal in the setting parameter window in the burger menu, then
Image Information and Information. If standard FITS keywords FOCALLEN, XPIXSZ, YPIXSZ, XBINNING
and YBINNING are read in the FITS HDU, the PSF will also compute the image scale in arcseconds per
pixel.
• 𝑟: The roundness parameter. It is expressed as FWHM𝑥 /FWHM𝑦 , with FWHM𝑥 > FWHM𝑦 the symmetry
condition.
• Another parameters is also fitted in both Gaussian and Moffat models. This is the rotation angle 𝜃, defined in
the range [−90, +90]. The addition of this parameter implies a coordinate change where the 𝑥 and 𝑦 variables
expressed in (10.1) and (10.2) are replaced by 𝑥′ and 𝑦 ′ :

𝑥′ = +𝑥 cos 𝜃 + 𝑦 sin 𝜃
(10.3)
𝑦 ′ = −𝑥 sin 𝜃 + 𝑦 cos 𝜃.

10.3 Minimization

Minimization is performed with a non-linear Levenberg-Marquardt algorithm thanks to the very robust GNU Scientific
Library. This algorithm is used to find the minimum of a function that maps a set of parameters to a set of observed
values. It is a combination of two optimization techniques: the gradient descent method and the inverse-Hessian
method.
The Levenberg-Marquardt algorithm adjusts the trade-off between these two methods based on the curvature of the
function being minimized. When the curvature is small, the algorithm uses the gradient descent method, and when the
curvature is large, the algorithm uses the inverse-Hessian method.
Since version 1.2.0, the saturated part of the star is removed from the fitting process, enabling to capture much more
accurately the non-saturated part. This is what enables to "reconstruct" the star profile when using the Desaturate menu
option or unclipstars command.

10.3. Minimization 237

Siril, Release 1.2.0

Fig. 2: Displays of two circular PSFs according to a Gaussian profile and a Moffat profile. Both models use the same
parameters and the Moffat profile uses uses 𝛽 = 1.4.

238 Chapter 10. Dynamic PSF

 Siril, Release 1.2.0

Fig. 3: Rotated Gaussian and Moffat function have 𝜎𝑥 = 2𝜎𝑦 , 𝜃 = 45. For Moffat, 𝛽 = 1.4.

10.3. Minimization 239

Siril, Release 1.2.0

Fig. 4: Star Profile with Gaussian and Moffat models. Several 𝛽 values are tried. 𝛽 = 10 gives a profile very close to
the Gaussian one.

240 Chapter 10. Dynamic PSF

 Siril, Release 1.2.0

10.4 Use

Dynamic PSF can be called from two different ways depending on what you want:
You may want to fit just one or a few stars. In this case, after drawing a selection around an unsaturated star (this is
important for the accuracy of the result) you can either right click and choose the Pick A Star item, click the + button
in the Dynamic PSF dialog, or type Ctrl + Space. An ellipse is then drawn around the star. To open the dialog it is
also possible to use the shortcut Ctrl + F6.

You may want to analyze as many stars as possible by clicking on the icon , or using the command line findstar.
All detected stars are surrounded by an ellipse: orange if the star is ok, magenta if the star is saturated. It is also possible

to show the average of the computed parameters as illustrated below, by clicking on the button.

Fig. 5: Average of the fitted stars in the Gaussian model.

Star detection has a number of uses:

• Siril uses it internally for astrometric purposes when registering sequences of images. This is automatic and
requires no user intervention.
• Because stars are so bright compared with dim features of interest such as nebulae or galaxies, it is very common
that some stars in an image will be saturated, meaning their brightness profile is clipped. This can cause problems
for some image processing functions, particularly deconvolution, and results in loss of colour information and

10.4. Use 241

Siril, Release 1.2.0

slightly greater star bloat when applying stretches. Analysis of all the stars will show you which ones are saturated,
and you can then use the Desaturate menu option or unclipstars command to fix the problem by synthesis of the
clipped part of the profile.

Siril command line

unclipstars

Re-profiles clipped stars of the loaded image to desaturate them, scaling the output so that all pixel values are
<= 1.0

• Ideally all stars in an image should be perfectly round, however problems such as coma, astigmatism and bad
tracking, as well as issues such as incorrect back focus to field flatteners, can give rise to patterns of elliptical
stars in an image. The ellipses produced by the Dynamic PSF tool can give a good visual illustration of such
problems.
• Examination of the average star parameters, especially FWHM and the Moffat fitting function beta parameter,
can provide information about the quality of seeing in an image.
• Detection of all stars is the first step in using the Star Tools → Full Resynthesis tool. This synthesizes corrected
luminosity profiles for all detected stars, and can be used to create a synthetic star mask which can then be
mixed with a starless image generated by Starnet++ to fix otherwise irredeemable stars in an image. In this case
detection of stars using the Moffat profile may give a more realistic result and can also make it easier to filter out
galaxies incorrectly detected as stars by using the Minimum beta setting.
• The Center Selected Star toggle button can be used to find a particular star in the list quickly and easily in the
image, by centring it in the viewport. This is useful if you have detected all stars and wish to check specific
solutions to ensure they really are a star and not a galaxy or a cosmic ray.
• Similarly to this, clicking on an orange or magenta star ellipse in the main viewport will highlight the selected
star solution in the Dynamic PSF dialog. This could be useful if you wish to see the parameters of an individual
star.
• Siril's deconvolution functions support using Dynamic PSF measurements to synthesize a deconvolution function
that matches star parameters measured directly from the image.

10.5 Configuration

Dynamic PSF can be configured using the settings in the Dynamic PSF dialog:
• Radius sets the half-size of the search box. If you have trouble detecting particular stars you can try changing
this but usually the default is fine.
• Threshold changes the threshold above the noise for star detection. If you increase this value, fewer faint stars
will be detected. You may still wish to do this for very noisy images though. Decreasing this value may detect
more faint stars, but will also make the algorithm more likely to misidentify random noise spikes as stars.
• Roundness threshold sets the allowable ellipticity for detections to be accepted as stars. Highly elliptical stars
may occur due to imperfect tracking or aberrations, but sometimes stars that are too close from each others are
also detected as a single very elongated star. To highlight all these problems, it is possible to enable a higher
bound for the roundness. A maximum value of 1 is equivalent to disabling the range, leaving only the minimum
value. This roundness range should be disabled for registration or astrometry.

242 Chapter 10. Dynamic PSF

 Siril, Release 1.2.0

• Convergence sets a criterion used by the solver. Increasing it will allow the solver more interations to converge
and can potentially detect additional stars, but may increase the solver running time.
• Profile type chooses between solving Gaussian or Moffat profiles for the stars.
• Minimum beta sets a minimum permissible value of beta for a detection to be accepted as a star. Galaxies may
sometimes be detected as Moffat profile stars but they have diffuse profiles and the value of beta is usually very
low, less than around 1.5.
• Relax PSF checks allows for relaxation of several of the star candidate quality checks. This is likely to result in
a significant increase in false positive star detections, often with wild parameters.
• A range of minimum and maximum amplitude can be set to limit the amplitude (parameter named A in reports)
of detected stars. This is useful if only non-saturated stars need to be selected, for PSF fitting in deconvolution
for example. Note that removing the saturated stars from detection can break registration and astrometry.

Tip: The settings defined in this window can be tested on the currently loaded image. However, you have to keep in
mind that they will also be used for all images of the sequence, especially for the global alignment registration.

The findstar command will obey the same settings entered in the Dynamic PSF dialog, but it can also be configured
using the setfindstar command.

Siril command line

findstar [-out=] [-layer=] [-maxstars=]

Detects stars in the currently loaded image, having a level greater than a threshold computed by Siril.
After that, a PSF is applied and Siril rejects all detected structures that don't fulfill a set of prescribed detection
criteria, that can be tuned with command SETFINDSTAR.
Finally, an ellipse is drawn around detected stars.

Optional parameter -out= allows the results to be saved to the given path.
Option -layer= specifies the layer onto which the detection is performed (for color images only).
You can also limit the maximum number of stars detected by passing a value to option -maxstars=.

See also CLEARSTAR

Links: psf , setfindstar, clearstar

Siril command line

setfindstar [reset] [-radius=] [-sigma=] [-roundness=] [-focal=] [-pixelsize=] [-

˓→convergence=] [ [-gaussian] | [-moffat] ] [-minbeta=] [-relax=on|off] [-minA=] [-

˓→maxA=] [-maxR=]

Defines stars detection parameters for FINDSTAR and REGISTER commands.

10.5. Configuration 243

Siril, Release 1.2.0

Passing no parameter lists the current values.

Passing reset resets all values to defaults. You can then still pass values after this keyword.

Configurable values:

-radius= defines the radius of the initial search box and must be between 3 and 50.
-sigma= defines the threshold above noise and must be greater than or equal to 0.05.
-roundness= defines minimum star roundness and must between 0 and 0.95. -maxR allows an upper bound to
roundness to be set, to visualize only the areas where stars are significantly elongated, do not change for registration.
-minA and -maxA define limits for the minimum and maximum amplitude of stars to keep, normalized between 0
and 1.
-focal= defines the focal length of the telescope.
-pixelsize= defines the pixel size of the sensor.
-gaussian and -moffat configure the solver model to be used (Gaussian is the default).
If Moffat is selected, -minbeta= defines the minimum value of beta for which candidate stars will be accepted and
must be greater than or equal to 0.0 and less than 10.0.
-convergence= defines the number of iterations performed to fit PSF and should be set between 1 and 3 (more
tolerant).
-relax= relaxes the checks that are done on star candidates to assess if they are stars or not, to allow objects not
shaped like stars to still be accepted (off by default)

Links: findstar, register, psf

10.6 References

244 Chapter 10. Dynamic PSF

 CHAPTER

ELEVEN

ASTROMETRY

Astrometry is the science dealing with the positions and motions of celestial objects. Astrometry is essential in modern
astrophotography where capture software like N.I.N.A, Ekos, APT or others, plate solve the images in order to obtain
an astrometric solution, meaning they will precisely know the position of the frame with regards to the sky. Astrometry
can also be used at processing stage, like in photometric color calibration tool for example.

11.1 Platesolving

The platesolving is a major step in astronomical image processing. It allows images to be associated with celestial
coordinates, giving the ability to know what object is in the observed field of view. Many of Siril's tools, such as the
Photometric Color Calibration (PCC) tool, need to know the coordinates of the image with sufficient accuracy in order
to work.
Astrometry in Siril can be performed in a few different ways:
• Using the dedicated tool accessible via the burger menu → Image Information → Image Plate Solver, or using
the shortcut Ctrl + Shift + A.
• Using the photometric color calibration tool, based on the same tool but extended to add star color analysis and
comparison with star colors in catalogs to adjust the image's color, available in the Image Processing menu →
Color Calibration → Photometric Color Calibration or using the shortcut Ctrl + Shift + P.
• Using the platesolve command, introduced in Siril 1.2.
Since version 1.2, plate solving can be done by two different algorithms. The first was the only one in Siril until this
version, it's based on the global registration's star matching algorithm, trying to register images onto a virtual image of
a catalog with the same field of view. The second is new, it is using an external program called solve-field from
the Astrometry.net suite, installed locally. For Windows platforms, the simplest way to get it is to use ansvr.
Astrometric solutions require a few parameters to be found, like image sampling. The window of the tool helps gathering
those parameters, we will now see how to fill them correctly.

11.1.1 Image parameters

Target coordinates

Finding an astrometric solution is easier and faster when we roughly know were we are looking. Siril's plate solver, as
it's comparing a catalog with the image, needs to know approximately the position of the center of the image to get the
catalog excerpt. Astrometry.net has all the catalogs it needs locally, so it can browse through all of it to find a solution,
but it is of course much faster to tell it where to start.
Acquisition software often also control the telescope nowadays and should know the approximate coordinates where
the image was taken. In that case, using a FITS format, these coordinates will be provided in the image metadata, the

245
Siril, Release 1.2.0

Fig. 1: Platesolving dialog

246 Chapter 11. Astrometry

 Siril, Release 1.2.0

Fig. 2: Photometric Color Calibration tool

11.1. Platesolving 247

Siril, Release 1.2.0

FITS header. This is not always the case, and clearly not the case when RAW DSLR images are created instead of
FITS.
When opening the plate solver or PCC windows, the current image's metadata is loaded and displayed in the window. If
no coordinates appear at the top, or if RA and Dec remain zero, some user input is needed. If you don't know at all what
the image is, use a blind solve with astrometry.net. Otherwise, provide equatorial J2000 coordinates corresponding to
as close as the center of the image as possible, either by filling the fields if you already know the coordinates, or by
making a query with an object name (not yet possible from the command).
The text field at the top left of the window is the search field, pressing Enter or clicking the Find button will make a
Web request to convert the object name to coordinates. Several results may be found with the entered name, they will
be displayed in the list below. Selecting one updates the coordinates at the top.
It is also possible to choose the server on which you want to execute the query, it does not change the results much, but
sometimes one of them can be online, so others would act as a backup, between CDS, VizieR and SIMBAD (default).

Note: If the object is not found, please change the name you enter: you need to use the name written in the astronomical
catalogue. For example, for the Bubble Nebula, please enter NGC 7635 and not Bubble Nebula.

The coordinate fields are filled in automatically, but it is possible to define your own. Don't forget to check the S box if
the object you are looking for is located in the southern hemisphere of the sky (negative declinations).

Image sampling

Image sampling is the most important parameter for plate solving. Given in arcseconds per pixel in our case, it represents
how much zoomed on the sky the image is, so how wide a field to search for.
It is derived from two parameters: focal length and pixel size. They are often available in the image metadata as well.
When not available from the image, the values stored in the settings are used. The values of the images and of the
preferences can be set using the Information dialog. In any case, check the displayed value before plate solving and
correct if needed. If an astrometric solution is found, the default focal length and pixel size will be overwritten. This
behavior can be disabled in the settings.

Warning: If binning was used, it should be specified in the FITS header, but this can take two forms: the pixel
size can remain the same and the binning multiplier should be used to compute the sampling, or the pixel size is
already multiplied by the acquisition software. Depending on the case you are facing, either of the forms can be
chosen from the preferences or from the Information window.

Pixel size is given in the specification of astronomical cameras, and can generally be found on the Web for DSLR or
other cameras. The number of sensors is limited and most of them are known.
Focal length depends on the main instrument, but also on backfocus and correcting or zooming lenses used. Give a
value as close as what you believe the effective focal to be, if an astrometric solution is found, the computed focal length
will be given in the results and you will be able to reuse that in your acquisition software and for future uses of the tool.
When either of the fields is updated, the sampling is recomputed and displayed in the window (called 'resolution' here).
Make sure the value is as close as reality as possible.

248 Chapter 11. Astrometry

 Siril, Release 1.2.0

Other parameters

Finally, there are three toggle buttons at the bottom of the frame:
1. The option Downsample image downsamples the input image to speed-up star detection in it. The downside is
that it may not find enough stars or give a less accurate astrometric solution. The size of the output image remains
unchanged.
2. If the image is detected as being upside-down by the astrometric solution, with the option Flip image if needed
enabled, it will be flipped at the end. This can be useful depending on the capture software, if the image has not
the right orientation when it is displayed in Siril (see more explanations).
3. When the option Auto-crop (for wide field) is applied, it performs a platesolve only in the center of the image.
This is only done with wide field images (larger than 5 degrees) where distortions away from the center are
important enough to fool the tool. Ignored for astrometry.net solves.

11.1.2 Catalogue parameters

By default, this section is insensitive because everything is set to automatic. By unchecking the auto box, however, it
is possible to choose the online catalog used for the platesolve, which may depend on the resolution of the image. The
choice is done between:
• TYCHO2, a catalogue containing positions, proper motions, and two-color photometric data for 2,539,913 of
the brightest stars in the Milky Way.
• NOMAD, a simple merge of data from the Hipparcos, Tycho-2, UCAC2, Yellow-Blue 6, and USNO-B catalogs
for astrometry and optical photometry, supplemented by 2MASS near-infrared. The almost 100 GB dataset
contains astrometric and photometric data for about 1.1 billion stars.
• Gaia DR3, released on 13 June 2022. The five-parameter astrometric solution, positions on the sky (, ), paral-
laxes, and proper motions, are given for around 1.46 billion sources, with a limiting magnitude of G = 21.
• PPMXL, a catalog of positions, proper motions, 2MASS- and optical photometry of 900 million stars and galax-
ies.
• Bright Stars, a star catalogue that lists all stars of stellar magnitude 6.5 or brighter, which is roughly every star
visible to the naked eye from Earth. The catalog contains 9,110 objects.

Note: An internet connection is required to use these online catalogs.

The Catalogue Limit Mag is an option that allows you to limit the magnitude of the stars retrieved in the catalog. The
automatic value is calculated from the image resolution.

Using local catalogues

With version 1.1, starting in June of 2022, it was possible to rely on a locally installed star catalogue, for disconnected
or more resilient operation. The star catalogue we found to be the most adapted to our needs is the one from KStars. It
is in fact composed of four catalogues (documented here in KStars), two of them not being directly distributed in the
base KStars installation files:
• namedstars.dat, the brightest stars, all of them have names
• unnamedstars.dat, also bright stars, but down to magnitude 8
• deepstars.dat, fainter stars extracted from The Tycho-2 Catalogue of the 2.5 Million Brightest Stars, down to
magnitude 12.5

11.1. Platesolving 249

Siril, Release 1.2.0

• USNO-NOMAD-1e8.dat, an extract of the huge NOMAD catalogue limited to B-V photometric information
and star proper motion in a compact binary form, down to magnitude 18.
When comparing these catalogues with the online NOMAD, we can easily see that many stars are missing. If not enough
are found for your narrow field, you should still use the remote queries. A nice thing to check when the catalogues are
installed is highlighting which stars of the image will be used for the PCC, those available with photometric information
in the catalogues, using the nomad command.

Download

The first two files are available in KStars source, the Tycho-2 catalogue from a debian package and the NOMAD
catalogue from KStars files too, as documented in this small article for KStars installation. It is has multiple worldwide
mirrors as indicated in the articles.
To make things easier to Siril users, and possibly to KStars users too, we redistribute the four files in a single place,
and in a more compressed format. With the LZMA algorithm (used by xz or 7zip), the file size is 1.0GB instead of the
1.4GB with the original gzip file.
To make it available from anywhere faster, it is distributed with bittorrent, using this torrent file or the following magnet
link.
Slower direct download links are available here (right click on each file name on the left and save the links).

Installation in Siril

The files can be put anywhere and their paths given to Siril in the settings, but there is a default location for the four
files: ~/.local/share/kstars/ on Linux. They can be linked there to avoid unnecessary copies. Settings can be
changed from the command line now, using the set command.
When available and readable, Siril will not use the Web service to retrieve astrometric or photometric data. See the
messages in the log tab or on the console to verify that the catalogue files are used as expected.
Only SIMBAD will be used to convert object names into coordinates if required, but that should only be needed if
the acquisition software did not record the target coordinates in the FITS header, or when using SER file format which
cannot hold this information.

Usage

With the addition of the new link between Siril's plate solver and the local catalogue and the new link between Siril's
PCC and the local catalogue, a new command nomad was created to display which stars in a plate solved image contain
photometric information (the B-V index) and can be used for calibration.
This is a good way to verify that the plate solving and the image are aligned, in addition to the object annotation feature
(see annotations).

250 Chapter 11. Astrometry

 Siril, Release 1.2.0

Fig. 3: Preferences with local catalogues

11.1. Platesolving 251

Siril, Release 1.2.0

Technical information

For photometry, Siril only uses the B-V index, which gives information about star colour. The three image channels
are then scaled to give the best colour representation to all stars in the image.
For more information about the KStar binary file type, see this page and this discussion on kstars-devel and some
development notes in Siril here and here.
Sha1 sums for the 4 catalogue files:

4642698f4b7b5ea3bd3e9edc7c4df2e6ce9c9f7d namedstars.dat
53a336a41f0f3949120e9662a465b60160c9d0f7 unnamedstars.dat
d32b78fd1a3f977fa853d829fc44ee0014c2ab53 deepstars.dat
12e663e04cae9e43fc4de62d6eb2c69905ea513f USNO-NOMAD-1e8.dat

Licenses for the 4 catalogue files.

11.1.3 Using the local astrometry.net solver

Since version 1.2, solve-field, the solver from the astrometry.net suite, can be used by Siril to plate solve images or
sequence of images.
For Windows platforms, the simplest way to get it is to use ansvr. If you did not modify the default installation directory,
that is %LOCALAPPDATA%\cygwin_ansvr, Siril will search for it without additional setup. If you have cygwin and
have build astrometry.net from the sources, you must specify the location of cygwin root in the Preferences.
For MacOS, please follow these instructions. Install with homebrew and add it to the PATH. Also make sure that the
program works for the test images, as indicated in the instructions, and outside of Siril.
For non-Windows OS, the executable is expected to be found in the PATH.
The use of this tool makes it possible to blindly solve images, without a priori knowledge of the area of the sky they
contain. It's also a good alternative to Siril's plate solver in case it fails, because it's a dedicated and proven tool that
also can take field distorsion into account.
Default settings should be fine, but can be modified if you really want to, using the set command (default values specified
between parens) or in the Astrometry tab of preferences. How wide the range of allowed scales is (15%), how big the
radius of the search from initial coordinates is (10 degrees), the polynomial order for field distorsion (0, disabled),
removing or not the temporary files (yes), using the result as new default focal length and pixel sizes (yes).

Index files

Astrometry.net needs index files to run. We strongly recommend you use the latest index files available from their
website, i.e. the 4100 and 5200 series. The field of view of each series is described in their github page. (the official
documentation does not yet include this table).
On Unix-based system, you can just follow along the instructions in the documentation.
On Windows, if you are running ansvr, those recent index files will not be made available by the Index Downloader. You
can still download them separately and store them where the other index files are kept (would recommend to remove
the old files, although it may mess up the Index Downloader).

252 Chapter 11. Astrometry

 Siril, Release 1.2.0

How it works

Just like the internal solver, Siril will proceed with extracting the stars from your images (so as to benefit from internal
parallelism) and submit this list of stars to astrometry.net solve-field. If you then want astrometry.net to crawl the
index in parallel, you will need to specify it through the astrometry.cfg file.

11.1.4 Star detection

By default, the star detection uses the findstar algorithm with the current settings. It works very well to find many
stars, but in some occasions we would like to detect the stars manually, or simply view which are used. A first step
would be to open the PSF window and launch star detection, then adjust the settings (see the related documentation
documentation).
Another approach would be to select the stars one by one by surrounding them with a selection then via a right click,
choose Pick a Star. The more stars selected, the more likely the algorithm is to succeed.
Then in the astrometry window, expand the star detection section and activate the Manual detection. Instead of running
findstar, it will use the current list of stars.

11.1.5 Understanding the results

When an astrometric solution is found, we can see in the Console tab this kind of messages:

232 pair matches.

Inliers: 0.996
Resolution: 0.196 arcsec/px
Rotation: -115.21 deg (flipped)
Focal length: 3959.95 mm
Pixel size: 3.76 µm
Field of view: 31' 15.46" x 20' 51.09"
Saved focal length 3959.95 and pixel size 3.76 as default values
Image center: alpha: 21h32m41s, delta: +57°36'22"
Flipping image and updating astrometry data.

The astrometric solution gives us the J2000 equatorial coordinates of the image center, the projected horizontal and
vertical dimension of the image on the sky, the focal length that could give this field for the given pixel size and
consequently the actual image sampling, the angle the image makes with the north axis and some information about
how many stars could be used to achieve the solution.
If it fails, check that start coordinates and pixel size are correct and try changing the input focal length from a factor 2,
this will change the amount of stars downloaded from the catalogs, and maybe more stars will be identified. If Siril's
plate solve won't find a solution, it is still possible to use an external tool to do it, the solution will be written in the
FITS header either way.

11.1. Platesolving 253

Siril, Release 1.2.0

11.2 Annotations

Annotations are glyphs displayed on top of images to depict the presence of known sky objects, like galaxies, bright
stars and so on. They come from catalogues but can only be displayed on images for which we know which part of the
sky they represent, images that have been plate solved and contain the world coordinate system (WCS) information in
their header, so only FITS or Astro-TIFF files.

Fig. 4: View of full annotated image

Plate solving, can be done within Siril in the Image Information → Image Plate Solver... entry, or using external tools
like astrometry.net or ASTAP.
When a plate solved image is loaded in Siril, you can see the sky coordinates for the pixel under the mouse pointer
displayed at the bottom right corner and the buttons related to annotations become available. The first button toggles
on or off object annotations, the second the celestial grid and the compass.

11.2.1 Types of catalogues

Siril comes with a predefined list of catalogues for annotations:

• Messier catalogue (M)
• New General Catalogue (NGC)
• Index Catalogue (IC)
• Lynds Catalogue of Dark Nebulae (LdN)

254 Chapter 11. Astrometry

 Siril, Release 1.2.0

Fig. 5: Buttons for annotations

• Sharpless Catalogue (Sh2)

• Star Catalogue (3661 of the brightest stars)
In addition, 2 user defined catalogues can be used:
• User DeepSky Objects Catalogue
• User Solar System Objects Catalogue

11.2.2 Catalogue management

Both these catalogues can be enabled/disabled for display in the Preferences menu → Astrometry tab.
A slider on the right side, allows you to easily navigate across the catalogue list.

Fig. 6: Catalogue management in Preferences/Astrometry

The two user defined catalogues can also be purged (ie deleted) via the appropriate buttons.

11.2. Annotations 255

Siril, Release 1.2.0

The user catalogues (DSO, SSO or extra catalogues) are stored in the user settings directory and can be easily modified.
Their location depends on the operating system:
• for Unix-based OS they will be in ~/.config/siril/catalogue
• on Windows they are in %LOCALAPPDATA%\siril\catalogue.
The position of the compass on the image can be adjusted from the preferences too.
These annotation catalogues are for display purposes only. They are not used in astrometry or photometry tools, contrary
to the star catalogues like NOMAD, which can now be installed locally too.

Fig. 7: Local Catalogue (NOMAD) setup

11.2.3 Searching for a new object

When the name of an object in the image is known (if not, see the Inverse Search section), it is possible to add it to
annotations:
• with the image loaded and plate solved, type Ctrl + Shift + / or Search in the pop-up menu (right click).
A small search dialog will appear. In it, object names can be entered, then pressing Enter will send an online request
to SIMBAD (for a star of Deep Sky Object) to get the coordinates of an object with such a name. If found, and not
already in any catalogue, the object will be added to the Deep Sky user Catalogue.
The items of this catalogue are displayed in ORANGE while the objects from the predefined catalogues are displayed
in GREEN.
From Siril version 1.2, we can now search for solar system objects too, using the Miriade ephemcc service. This is done
by prefixing the name of the object to be searched by some keyword representing the type of object: a: for asteroids,
c: for comets, p: for planets. Since they are moving objects, they can be added several times, and the request is done
for the date of observation of the currently loaded image. The date is associated to the name in the user Solar System
Catalogue. The items of this catalogue are displayed in YELLOW.
Examples of valid inputs (not case sensitive):
• HD 86574 or HD86574 are both valid for this star

256 Chapter 11. Astrometry

 Siril, Release 1.2.0

Fig. 8: Deep sky objects from user and predefined catalogues

11.2. Annotations 257

Siril, Release 1.2.0

• c:67p or c:C/2017 T2 are valid forms for comets

• a:1 and a:ceres are both valid for (1) Ceres
• a:2000 BY4 is valid for 103516 2000 BY4
• p:4 or p:mars for Mars

11.2.4 Filling a Solar System user Catalogue: which SSO is in this field?

To answer the question Is there any solar system object in my image?, a special function does a request to an online
server of the IMCCE too (SkyBoT) and displays the results in the console and in the image.
• with the image loaded and plate solved, right click/Solar System Objects, or in the command line you can
use the solsys function.
It displays in RED all the Solar System objects in the field of view (if any are known and found of course). Objects
magnitudes and equatorial coordinates for the image date are printed in the console.
These red annotations will be erased as soon as the Show Objects names button is toggled.

Fig. 9: Result of a Search Solar System process

However, you may want to save any particular item in the User Solar System Objects Catalogue. It can be done by
using the Search command for a solar system object as previously described.
This way, the saved item is diplayed in YELLOW and will be displayed in any image that has this field of view by
enabling the annotations.

Note: Newly discovered objects, or some fast moving objects, will have their position misaligned with the image. This
is often the case for comets for example, which can be an arcminute off. This happens because the orbital parameters

258 Chapter 11. Astrometry

 Siril, Release 1.2.0

Fig. 10: View with predefined/DSO/SSO

11.2. Annotations 259

Siril, Release 1.2.0

of the object are not very well known or that they have not been updated recently in the system. If you are looking for
an alternate computation of the coordinates of the known objects of the field, you might query manually the JPL Small
Body identification tool.

11.2.5 The inverse search: what is this object?

Especially useful for photometry works, it is possible to identify a star or other objects in the image by drawing a
selection around them, right clicking to bring up the context menu, and selecting the PSF entry. This will open the PSF
window, and if it’s a star it will display the Gaussian fit parameters, but it will also display a Web link at the bottom
left of the window: opening it will bring you to the SIMBAD page for the coordinates of the object and in many cases
will give you the name of the object. SIMBAD doesn’t have all known objects, but the coordinates from the page can
still be used as a starting point to look for the object in other online catalogues, for example Gaia DR3 (VizieR).

11.2.6 Extra catalogues

Sometimes, users create their own catalogues, we can try to link them here to help everybody. They are user catalogues,
so installing them requires either replacing the current user catalogue, or by manually merging their lines into a new
file.
List of known user catalogues:
• Variable stars, extracted from GCVS 5.1, discussed here in French, (file link).

260 Chapter 11. Astrometry

 CHAPTER

TWELVE

PHOTOMETRY

This section introduces you to all the utilities related to photometry, first explaining the principles of photometry, then
how it is used in Siril.
Siril is able to determine the magnitude of stars as well as its uncertainty. From there it is possible to study the variability
of certain stars, exoplanets, or occultations. A light curve is also built at the end of the process.

Warning: For an unrestricted use of photometry in Siril, we recommend to install the gnuplot software. Without
it, Siril can't build or display light curves.

Fig. 1: Example of exoplanet photometry in Siril.

261
Siril, Release 1.2.0

12.1 Principles

Photometry is the science of the measurement of light. It aims to measure the flux or intensity of light radiated by
astronomical objects. In Siril, photometry can be used to analyze the light curve of variable stars, transits of exoplanets
or occultations of stars, or to calibrate colors in RGB images.
Aperture photometry is the method used. Its basic principle is to sum-up the observed flux in a given radius from the
center of an object, then subtract the total contribution of the sky background in the same region (calculated in the
ring between the inner and outer radii, excluding the deviant pixels), leaving only the flux of the object to calculate an
instrumental magnitude. This is illustrated in the following figure.

Fig. 2: Circles of the aperture photometry

The values of these settings can be changed in the Photometry section of preferences or using the setphot command.
The aperture must contain all pixels of the object to measure, the annulus should by opposition not contain any of its
pixels. By default, the aperture is adjusted for a target using twice the PSF's FWHM, but the annulus size is fixed.
These values should be adjusted for a given sampling, and checked with care.

Note: The following text is a truncated and modified copy of the excellent MuniPack software documentation, from
David Motl and released under the GNU Free Documentation License, whose sources are available here.

262 Chapter 12. Photometry

 Siril, Release 1.2.0

Measuring magnitude of an object

The sum S of pixels in a small area A around an object is a sum of the object's net intensity I plus background intensity
𝐵 · 𝐴:

𝑆 =𝐼 +𝐵·𝐴 (12.1)

The values of S and B are derived from the source frame, the area A is determined as the area of circle of radius r,
where r is the size of the aperture in pixels. It is then easy to compute the net intensity I of an object in ADU:

𝐼 =𝑆−𝐵·𝐴 (12.2)

Supposing that the net intensity I is proportional to the observed flux F, we can derive the apparent magnitude m of
the object, utilizing the Pogson's law:
(︂ )︂
𝐼
𝑚 = −2.5 log10 (12.3)
𝐼0

Estimating the measurement error

Once we have derived the raw instrumental brightness of an object, we will try to estimate its standard error. First of
all, we will recall a few general rules that apply to the standard error and its propagation. This is a general rule for error
propagation through a function f of uncertain value X:
(︂ )︂2
𝑑𝑓
Var(𝑓 (𝑋)) = Var(𝑋) (12.4)
𝑑𝑥
Using this general rule, we derive two laws of error propagation. In the first case, the uncertain value X is multiplied
by a constant a and shifted by a constant offset b. This law can also be used in the case where only a multiplication or
only an offset occurs.

Var(𝑎𝑋 + 𝑏) = 𝑎2 Var(𝑋) (12.5)

The second law defines the error of a logarithm of uncertain value X:

Var(𝑋)
Var(log(±𝑏𝑋)) = (12.6)
¯2
𝑋
Please note, that the log function here is the natural logarithm, while the Pogson's formula (see above) incorporates the
base-10 logarithm. The following equation helps us to deal with this difference:
log𝑘 (𝑥)
log𝑏 (𝑥) = (12.7)
log𝑘 (𝑏)
Putting these two equations together we get:
Var(𝑋)
Var(log10 (±𝑏𝑋)) = ¯ 2 (12.8)
𝑋 log(10)2
If we have two uncorrelated uncertain variables X and Y, the variance of their sum is the sum of their variances, this
equation is known as Bienaymé formula.

Var(𝑋 + 𝑌 ) = Var(𝑋) + Var(𝑌 ) (12.9)

From this formula, we can also derive the standard error of a sample mean. If we have N observations of random
variable X with sample-based estimate of the standard error of the population s, then the standard error of a sample
mean estimate of the population mean is
𝑠
𝑆𝐸𝑋¯ = √ (12.10)
𝑁

12.1. Principles 263

Siril, Release 1.2.0

Armed with this knowledge, we can start thinking about the estimation of standard error of object brightness. We will
consider the following three sources of uncertainty: (1) random noise inside the star aperture that includes the thermal
noise of the detector, read-out noise of the signal amplifier and the analog-to-digital converter, (2) Poisson statistics of
counting of discreet events (photons incident on a detector) that occur during a fixed period of time and (3) the error
of estimation of mean sky level.
For the estimation of mean sky level, we have used the robust mean algorithm. It allows to estimate its sample variance
2
𝜎𝑝𝑥𝑙 . This is a pixel-based variance and because we have summed together A pixels in the star aperture, the Bienaymé
formula applies, the sum S is a sum of A uncorrelated random variables, each of which has variance 𝜎𝑝𝑥𝑙 2
. For the
variance of the first source of error we get:

𝜎12 = 𝐴 𝜎𝑝𝑥𝑙
2
(12.11)

where A is a number of pixels in the star aperture.

From Poisson statistics we can derive a variance that occur due to counting of discreet events, photons incident on a
detector, that occur during a fixed period of time, the exposure. We will again need to use the gain p of the detector
to convert a intensity in ADU to a number of photons. If the measured net intensity of an object is I we compute the
mean number of photons 𝜆 as

𝜆=𝐼𝑝 (12.12)

Note: The value of the gain p of the detector can be changed in the Photometry section of Siril's preferences

Then, the variance of intensity due to Poisson statistics is equal to its mean value.
2
𝜎𝑝ℎ = Var(Pois(𝜆)) = 𝜆 = 𝐼 𝑝 (12.13)

The variance is in photons, we have to convert it back to ADU to get the variance in units 𝐴𝐷𝑈 2 .
2
𝜎𝑝ℎ 𝐼𝑝 𝐼
𝜎22 = = 2 = (12.14)
𝑝 2 𝑝 𝑝
We have derived the sky level as a sample mean of pixel population in the sky annulus. Because each pixel in the
annulus has variance 𝜎𝑝𝑥𝑙
2
, the variance of sample mean is
2
𝜎𝑝𝑥𝑙
𝑠2𝑠𝑘𝑦 = (12.15)
𝑛𝑠𝑘𝑦

where 𝑛𝑠𝑘𝑦 is the number of pixels in sky annulus.

From equation (12.9) we compute the variance of object's intensity as
2
𝜎𝐴𝐷𝑈 = 𝜎12 + 𝜎22 + 𝐴2 𝑠2𝑠𝑘𝑦 (12.16)

Note, that in equation (12.2) the sky level is multiplied by A, so we have to multiply its variance by 𝐴2 - see the equation
(12.16). Now, we use the law of error propagation for the logarithm adopted to match the formula of the Pogson's law.
(︂ )︂2
−2.5
2
𝜎𝑚𝑎𝑔 = 2
𝜎𝐴𝐷𝑈 (12.17)
𝐼 log(10)

Putting equations (12.17) and (12.16) together, we can derive the standard error of the object's brightness in magnitudes
as
1.08574
√︁
𝜎𝑚𝑎𝑔 = 2
𝜎𝐴𝐷𝑈 (12.18)
𝐼

264 Chapter 12. Photometry

 Siril, Release 1.2.0

12.2 Quick photometry

12.2.1 Photometry on hand-picked objects of a single image

The quick photometry button is a button located in the toolbar and used to perform a photometry of the stars,
this is generally the simpliest way to proceed.

Tip: If the star is in the middle of several stars and the tool fails to point to the right star, an alternative solution is
to draw a selection around the star and then right-click and click on PSF. It may also be interesting to know that the
middle click draws a selection of a recommended size for PSF/photometry (based on the configured outer radius).

Tip: When photometry is performed on the RGB layer, the results are actually calculated on the green layer. To obtain
photometry on the red or blue layers, you need to work on the corresponding channels.

Siril command line

psf [channel]

Performs a PSF (Point Spread Function) on the selected star and display the results. For headless operation, the
selection can be given in pixels using BOXSELECT. If provided, the channel argument selects the image channel on
which the star will be analyzed. It can be omitted for monochrome images or when run from the GUI with one of the
channels active in the view

Links: boxselect

Click on this button to change the image selection mode, then click on a star. The photometry and the PSF (Point
Spread Function) of the star are computed, giving plenty of details.
Two models are used for the calculation of the PSF, which can be selected by the user in the Dynamic-PSF window
(Ctrl + F6).
The result of the photometry and the associated PSF are displayed in the form:

PSF fit Result (Gaussian, monochrome channel):

Centroid Coordinates:
x0=5258.25px 09h25m34s J2000
y0=2179.72px +69°49'31" J2000

Full Width Half Maximum:

FWHMx=7.13"
FWHMy=6.79"
r=0.95
Angle:
82.87deg
(continues on next page)

12.2. Quick photometry 265

Siril, Release 1.2.0

Fig. 3: Photometry results window.

(continued from previous page)

Background Value:
B=0.000874

Maximal Intensity:
A=0.628204

Magnitude (relative):
m=-2.3948±0.0014

Signal-to-noise ratio:
SNR=28.9dB (Good)

RMSE:
RMSE=1.890e-03

1. The fit was done with the Gaussian fitting function so no additional parameters are needed. However, if Moffat
was used, the following output will be shown:

PSF fit Result (Moffat, beta=2.9, monochrome channel):

2. Centroid Coordinates gives the coordinates of the centroid in pixels. However, like in the example above, if
astrometry was set on the image, Siril gives coordinates in the World Coordinate Systems (RA and Dec).
3. Full Width Half Maximum (FWHM) is returned in arcsec if the image scale is known (obtained from its header
or from the GUI Image information → Information) and in pixels if not. The roundness r is also computed as

266 Chapter 12. Photometry

 Siril, Release 1.2.0

FWHMy
the ratio of FWHMx .

4. Angle is the rotation angle of the X axis with respect to the centroid coordinates. It varies in the range [−90, +90].
5. Background Value is the local background in the [0, 1] range for 32-bits images and [0, 65535] for 16-bits images.
This is a fitted value, not the background computed in the aperture photometry annulus.
6. The maximum Intensity value is also a fitted value and represents the amplitude. It is the maximum value of
the fitted function, located at the centroid coordinates.
7. The magnitude, given with its uncertainty, is the result of photometry. However, if for some reasons the cal-
culation cannot be done (saturated pixels or black pixels), an uncertainty of 9.999 is given. In this case, the
photometry is flagged as invalid but a magnitude value is still given, although it should be used with caution.
8. An estimator of the signal-to-noise ratio is shown in the results. Its value is calculated from the following
formula and given in dB:
(︂ )︂
𝐼
SNR = 10 log10 (12.19)
𝑁

where I is the net intensity, proportional to the observed flux F and N the total of uncertainties as expressed in
(12.18).
For easier understanding, it is associated with 6 levels of quality:
1. Excellent (SNR > 40dB)
2. Good (SNR > 25dB)
3. Satisfactory (SNR > 15dB)
4. Low (SNR > 10dB)
5. Bad (SNR > 0dB)
6. N/A
This last notation is displayed only if the computation failed, for one reason or another.
9. Finally, RMSE gives an estimator of the fit quality. The lower the value, the better the result.
When the image is plate-solved, the button More details at the bottom of the window links to a page on the SIMBAD
website with information about the selected star. However, it is possible that the page does not give any additional
information if the star is not in the SIMBAD database.

12.2.2 Quick photometry on sequences

Quick photometry can also be performed on a sequence. This is generally intended to obtain a light curve as explained
here. To proceed, you must load a sequence, make a selection around a star, then right click on the image.

Tip: Ideally, the sequence must be registered without interpolation so as not to alter the raw data. For example, use
the global registration with the option Save transformation in seq file only.

Note: Make sure the inner and outer radii for the background annulus are adapted to the star and sequence being
analyzed. Some images may have much larger FWHM than the reference image, because of sky conditions or bad
tracking. They can be changed in the preferences or with the setphot command.

12.2. Quick photometry 267

Siril, Release 1.2.0

Fig. 4: More details about the analyzed star. Click on the picture to enlarge.

At the end of the process, Siril automatically opens the plot tab showing computed curves. It is possible to click on
several stars to reproduce the calculation, however the first star keeps the particular status of variable, and the others
serve as references. This is important in the calculation of the light curve.

12.2.3 Computing true magnitudes

The calculated magnitude is only meaningful if it is compared to others in the linear image. Indeed, the value given
does not correspond at all to the true visible magnitude of the star, it is uncalibrated, also called relative magnitude.
Siril provides tools that can be used to calculate an approximate apparent magnitude. This requires knowing the mag-
nitude of another star visible on the image that will act as reference. It is currently possible to use only a single star as
reference, hence the approximate. For a greater precision, use a star of similar color and magnitude as the star(s) you
want to measure should be chosen, and its provided magnitude should be in adequation with the filter used to capture
the image. Catalogs contain magnitudes computed using a photometric filters, which is generally not what amateur use
to make nice pictures, this adds another approximation.
• Do a quick photometry on a known star, the given relative magnitude is -2.428. It is possible to find out the
actual visible magnitude by clicking on the More details button as explained above. Let's say the value found is
11.68 (make sure you use a value corresponding to the spectral band of the image).
• Once done, keep the star selected, then enter the following command in Siril

setmag 11.68

That will output something like

10:50:49: Relative magnitude: -2.428, True reduced magnitude: 11.680,␣

˓→Offset: 14.108

Siril command line

setmag magnitude

268 Chapter 12. Photometry

 Siril, Release 1.2.0

Fig. 5: In this example, 3 stars have been analyzed. The first one is used as variable. The others are references.

Calibrates the magnitudes by selecting a star and giving the known apparent magnitude.

All PSF computations will return the calibrated apparent magnitude afterwards, instead of an
apparent magnitude relative to ADU values. Note that the provided value must match the magnitude
for the observation filter to be meaningful.
To reset the magnitude constant see UNSETMAG

Links: psf , unsetmag

• Now, all calculated magnitudes must have values close to their true visual magnitude. However, this is especially
true for stars whose magnitude is of the same order of magnitude as the star taken as reference.
• To unset the computed offset, just type

unsetmag

Siril command line

unsetmag

Resets the magnitude calibration to 0. See SETMAG

Links: setmag

12.2. Quick photometry 269

Siril, Release 1.2.0

Fig. 6: Photometry results window with true magnitude set.

270 Chapter 12. Photometry

 Siril, Release 1.2.0

Tip: The same commands exist for the sequences. They are seqsetmag and sequnsetmag. It is used in the same
way when a sequence is loaded.

Siril command line

seqsetmag magnitude

Same as SETMAG command but for the loaded sequence.

This command is only valid after having run SEQPSF or its graphical counterpart (select the area around a star and
launch the PSF analysis for the sequence, it will appear in the graphs).
This command has the same goal as SETMAG but recomputes the reference magnitude for each image of the
sequence where the reference star has been found.
When running the command, the last star that has been analysed will be considered as the reference star. Displaying
the magnitude plot before typing the command makes it easy to understand.
To reset the reference star and magnitude offset, see SEQUNSETMAG

Links: setmag, seqpsf , psf , sequnsetmag

Siril command line

sequnsetmag

Resets the magnitude calibration and reference star for the sequence. See SEQSETMAG

Links: seqsetmag

12.3 Light curves

In astronomy, a light curve is a graph of light intensity of a celestial object as a function of time, typically with the
magnitude of light received on the y axis and with time on the x axis. Siril is able to generate such curves when
analyzing stars.
There are now two ways of selecting the variable and references (also called comparison) stars: manually, or using a
list of stars obtained by the N.I.N.A. exoplanet plugin.

12.3. Light curves 271

Siril, Release 1.2.0

12.3.1 Manual star selection

Start by selecting stars and running photometry analysis on the sequence for each, as explained here.

Fig. 7: One star is the variable (purple with a V) and the 5 others are used as references.

Warning: Make sure to not select variable stars for references. If the astrometry is done on your image, do not
hesitate to use the SIMBAD request to know more about the stars.

Tip: It is preferable to choose references whose magnitude is close to that of the variable.

Once done, Siril automatically loads the Plot tab as shown in the figure below. This shows FWHM curves expressed
as a function of frame number.
What interests us in this part is to display the magnitude curves. Simply go to the drop-down menu and change FHWM
to Magnitude. The magnitude curves of each analyzed star are then displayed. This also results in the button Light
Curve being sensitive. It is also recommended to check the Julian Date button in order to plot magnitude as a function
of a date.
Once the analysis is completed with a number of reference stars of at least 4 or 5 (the higher the number, the more
accurate the result), you can click on the Light Curve button. Siril will ask for a file name to save the data in csv

272 Chapter 12. Photometry

 Siril, Release 1.2.0

Fig. 8: The plot tab as showed right after the quick photometry on sequence.

12.3. Light curves 273

Siril, Release 1.2.0

Fig. 9: Switching to magnitude view make the Light Curve button sensitive.

274 Chapter 12. Photometry

 Siril, Release 1.2.0

format, then the light curve will be displayed in a new window. The csv file can of course be used in any other software
or website to reduce the data.

Warning: As already mentionned, the software gnuplot must be installed to be able to see light curves.

Light Curve

-1.405

-1.4

-1.395

-1.39

-1.385

-1.38

-1.375

-1.37

-1.365

-1.36

-1.355

-1.35
0.26 0.28 0.3 0.32 0.34 0.36 0.38 0.4 0.42 0.44

(JD) 2457403 +

Fig. 10: Light curve of an exoplanet transit.

12.3.2 NINA exoplanet button

In order to automate the process of transit analysis of exoplanets, lists of reference stars, also called comparison stars,
could be obtained from star catalogues, with the appropriate criteria: similar magnitude, similar color (to not change
their relative magnitude with atmospheric extinction at different elevations), proximity.
The capture software N.I.N.A has an exoplanet plugin that will show such stars and allow the list to be saved in a CSV
file, such as csv file:

Type,Name,HFR,xPos,yPos,AvgBright,MaxBright,Background,Ra,Dec
Target,HD 189733 b,2.6035068712769851,1992,1446,1640.3703703703704,39440,1917.
˓→0601851851852,300.18333333333328,22.709722222222222

Var,SW Vul,2.8626145609282911,2972,276,26.14,2012,1905.445,300.02171,22.93517
Var,DQ Vul,2.372369130017419,3006,1040,28.180555555555557,2048,1906.9027777777778,300.
˓→01254,22.78103

Var,HQ Vul,3.8351043206620834,157,1690,49.393939393939391,2104,1905.7454545454545,300.
˓→55808,22.64067

...
Comp1,ATO J300.3222+22.7056,2.4268101078425852,1367,1465,352,4496,1913.9504132231405,300.
(continues on next page)

12.3. Light curves 275

Siril, Release 1.2.0

(continued from previous page)

˓→ 32229415181337,22.705681453738887
Comp1,HD 189657,2.5343988482845927,2527,2808,23.814814814814813,2012,1906.5061728395062,
˓→300.08714683055996,22.4400393728

...
Comp2,000-BJP-946,2.2738807043120195,1832,750,29.962962962962962,2024,1910.0648148148148,
˓→300.23741666666666,22.846999999999998

Comp2,000-BJP-942,2.0977710589704297,2760,1572,31.083333333333332,2096,1908.
˓→6527777777778,300.025875,22.704777777777778

...

In the Plot tab, Siril can load this file using the NINA exoplanet button. To use this, a few prerequisites must be met:
• the sequence of calibrated images must be already loaded
• the reference image of the sequence must be plate solved, to make sure we identify the correct stars from their
equatorial J2000 coordinates
• gnuplot is installed to create or show the light curve, otherwise only the data file will be created.
From there, everything is automatic, showing the light curve for the selected comparison stars at the end of the process.
The following video shows an automated processing of light curve with comparison star list from NINA:

12.3.3 Commands and automatic operation

It is also possible to automate or create the light curve remotely using the light_curve command. As blind operation
needs as much automation as possible, the configuration of the background annulus radii can be automated with the
-autoring argument: it runs a star detection in the reference image and multiplies the mean FWHM with a configurabe
factor to obtain the inner and outer radii that should work with the sequence.

Siril command line

light_curve sequencename channel [-autoring] { -at=x,y | -wcs=ra,dec } { -refat=x,y | -

˓→refwcs=ra,dec } ...

light_curve sequencename channel [-autoring] -ninastars=file

Analyses several stars with aperture photometry in a sequence of images and produces a light curve for one,
calibrated by the others. The first coordinates, in pixels if -at= is used or in degrees if -wcs= is used, are for the star
whose light will be plotted, the others for the comparison stars.
Alternatively, a list of target and reference stars can be passed in the format of the NINA exolpanet plugin star list,
with the -ninastars= option. Siril will verify that all reference stars can be used before actually using them. A data
file is created in the current directory named light_curve.dat, gnuplot plots the result to a PNG image if available
The ring radii for aperture photometry can either be configured in the settings or set to a factor of the reference
image's FWHM if -autoring is passed.

See also SEQPSF for operations on single star

Links: seqpsf

276 Chapter 12. Photometry

 CHAPTER

THIRTEEN

IMAGE INSPECTORS

Siril has several tools that can help you to analyze your image and tell you about the quality of the shot. In particular
if your setup has or not optical defects.

13.1 Tilt

The first tool proposed by Siril is the tilt calculation. Sensor tilt occurs when the sensor is not orthogonal to the imaging
plane: this requires an intervention on the optical system. You can execute this functionality in two different ways.

Either via the GUI (clicking on the tilt button on the Dynamic PSF Window, Ctrl + F6) or via the command
line. The latter even offers an alternative that allows you to calculate the tilt over a whole sequence of images for greater
accuracy. The following command:

Siril command line

tilt [clear]

Computes the sensor tilt as the FWHM difference between the best and worst corner truncated mean values. The
clear option allows to clear the drawing

will output:

22:28:13: Running command: tilt

22:28:13: Findstar: processing for channel 0...
22:28:15: Stars: 7598, Truncated mean[FWHM]: 3.40, Sensor tilt[FWHM]: 0.31 (9%), Off-
˓→axis aberration[FWHM]: 0.39

In the console are indicated:

• the number of stars used for the measurement
• the average FWHM on the sensor, free of outliers
• the tilt, expressed as the difference between the best and the worst FWHM on the 4 corners of the image with in
parenthesis the percentage of tilt deviation (value greater than 10% indicates a tilt problem)
• the aberration, expressed by the difference in FWHM between the stars in the center and the stars on the edges
of the sensor

277
Siril, Release 1.2.0

If the number of stars detected is low (<200), the dynamic PSF detection parameters allow improvement by adjusting
the threshold / radius. In fact, the greater the number of stars used in the calculation, the more reliable the result of the
analysis.

Warning: For the result to make sense, it is preferable to run this command on a sub and not a stacking result. A
pre-processed image (just demosaiced for color sensors) is therefore ideal. Moreover, the drawn quadrilateral has
its proportions exaggerated, in order to be more visible on the screen. It can’t correspond exactly to reality.

Fig. 1: Display of the tilt diagram

Tip: As well as using the tilt -clear command, the tilt diagram can be cleared using the Remove button in the Dynamic
PSF dialog.

Siril command line

seqtilt sequencename

Same command as TILT but for the sequence sequencename. It generally gives better results

Links: tilt

278 Chapter 13. Image inspectors

 Siril, Release 1.2.0

13.2 Aberration Inspector

This tool creates a 3x3 mosaic of the image center, corners and edges. This makes it easy to compare the shape of
the star in different sections of the image. You can access this feature by right-clicking on the image and selecting
Aberration Inspector. You can change the settings of this tool, to modify the size of the panels and the window, in the
preferences.

Fig. 2: Aberration inspector window showing aberration in the stars located in the edges because of the optical system.

It is also a very good indicator to know if the image contains a gradient: the differences in brightness becoming very
visible.

Siril command line

inspector

Splits the loaded image in a nine-panel mosaic showing the image corners and the center for a closer inspection (GUI
only)

13.2. Aberration Inspector 279

Siril, Release 1.2.0

Fig. 3: Aberration inspector window showing differences in brightness.

280 Chapter 13. Image inspectors

 CHAPTER

FOURTEEN

STATISTICS

This is a documentation for Siril's statistics, given by the graphical user interface (GUI) from the contextual menu of
images (right-clicking in it) then selecting Statistics..., from the Image Information submenu of the application menu
after also selecting Statistics... or using the stat command. Note that when using the GUI, it is possible to draw a
selection in the loaded image and that when doing so, the statistics are computed on the pixels of region.
The option Per CFA channel allows you to calculate statistics for each R, G and B channel in CFA images, even if the
image has not been demosaiced.
Many of these values are measures of statistical dispersion.

Fig. 1: One channel statistics for CFA image. The given values are not really relevant in this case.

Siril command line

stat [-cfa] [main]

Returns statistics of the current image, the basic list by default or the main list if main is passed. If a selection is

281
Siril, Release 1.2.0

Fig. 2: Three channel statistics for CFA image.

made, statistics are computed within the selection. If -cfa is passed and the image is CFA, statistics are made on
per-filter extractions

14.1 Estimators

14.1.1 Mean

This is the arithmetic mean, also known as average or arithmetic average. This is computed by doing the sum of the
pixel values divided by the number of pixels in an image channel.

282 Chapter 14. Statistics

 Siril, Release 1.2.0

14.1.2 Median

The median is the value separating the higher half from the lower half of a dataset. Generally, it represents the value
of the background of an astronomical image.

14.1.3 Sigma

Also known as the standard deviation, noted 𝜎, this is a measure of dispersion of the image pixels based on squared
differences from the average. The sigma value of a sub image containing only the background will represent the noise
of the image.

14.1.4 Background noise

This estimator is available by the GUI from the Image Information submenu of the application menu after selecting
Noise estimation, and is also displayed at the end of stacking.
This is a measure of estimated noise in image background level, for pixels having a value low enough to be considered
as background. It is an iterative process based on k.sigma (a factor of the standard deviation above the median), so
there is no fixed threshold for the low enough.

Siril command line

bgnoise

Returns the background noise level of the loaded image

14.1. Estimators 283

Siril, Release 1.2.0

14.1.5 avgDev

The Average Deviation, also called AAD for average absolute deviation or mean absolute deviation. In order to under-
stand what the average deviation is, one needs to understand what the term absolute deviation is. Absolute deviation is
the distance between each value in the dataset and that dataset's mean (in this instance) or median (for MAD below).
Taking all of these absolute deviations, finding the average, and the mean average deviation is computed. To simplify,
if standard deviation is the squared deviation from the mean, this is the linear version of it.

14.1.6 MAD

The Median Absolute Deviation is a robust measure of how spread out a set of data is. The absolute deviation and
standard deviation are also measures of dispersion, but they are more affected by extremely high or extremely low
values. It is similar to the average deviation above, but relative to the median instead of the mean.

14.1.7 BWMV

The biweight midvariance is yet another tool to measure dispersion of a dataset, even more robust than others cited
above to outliers. It discards the data points too far way from the median and computes a weighted variance, weights
decreasing
√ as the data points are further way from the median. The estimator of dispersion is the square root (marked
as 𝐵𝑊 𝑀 𝑉 ) of this value.

14.1.8 Location and Scale

These parameters, often colloquially called scale and offset, are not displayed in the user interfaces but are computed
internally by Siril. In order to align the histograms of the different images for normalization before stacking, one needs
to compute where they are in terms of level and how √ wide they are in terms of spread. A valid estimator of location
could be taken as the median while the MAD or the 𝐵𝑊 𝑀 𝑉 could be used for scale. However, in order to give
more robustness to the measures,
√ the pixels more than 6 × MAD away from the median are discarded. On this clipped
dataset, the median and 𝐵𝑊 𝑀 𝑉 are re-computed and used as location and scale estimators respectively. They are
computed relative to the reference image of a sequence in Siril.

284 Chapter 14. Statistics

 CHAPTER

FIFTEEN

SCRIPTS

Siril has a command line in its graphical user interface and an ability to run scripts that are a list of commands, either
from the graphical user interface or from the command line interface. In general, commands that modify a single image
work on the currently loaded image, so the use of the load command is required in scripts, and commands that work
on a sequence of images take the name of the sequence as argument. If files are not named in a way that Siril detects
as a sequence, the command convert will help.

Tip: The Space character is the delimiter between arguments. If you need to have spaces inside the arguments, you
can use the quote or double quote, just like in a shell.

Commands can be typed in the command line at the bottom of Siril's main window. Another way is to put commands
in a file and execute it as a script. To execute the file from the GUI, add it to the configured script directories or from
the GUI, use the @ token of the command line like so:

@file_name

Some commands (preprocess, stack, and all save commands) can use file names containing variables coming from the
FITS header. The format of the expression is explained in details here and can be tested using the parse command.

15.1 Using scripts

There are three ways to run a script:

• from the graphical user interface, using the @ keyword on the command line, followed by the script name in the
current working directory,
• from the graphical user interface, using the Scripts menu,

285
Siril, Release 1.2.0

• from the command line interface (siril-cli executable), using argument -s followed by the script's path (see
the man page for more info).
The scripts menu only appears if some scripts have been found in the script search directories defined either by default
or by the user in the preference menu.

15.2 Populating the list of scripts

By default, when Siril is installed, a number of scripts are automatically installed. These built-in scripts, the official
ones, are developed by the development team and are guaranteed to work: they are meant to cover specific use cases.

15.2.1 Adding custom scripts folders

You can, of course, write your own and tell Siril where to find them:
• Click on the Burger icon then on Preferences (or hit Ctrl+P).
• Click on the Scripts section.
• Copy to a new line the path to the location to store them (create a folder on your computer as required or point
to an existing one).
• Click on the Refresh icon just below.
• Click on Apply.
You can have as many user-defined folders as you wish, just add them to the list.
If you have just added a new script in one of the folders and wish to refresh the menu, type the command reloadscripts
in the command line or open the Preferences → Scripts section and use the Refresh icon. This scans all the folders of
the list and find all the files with the *.ssf extension.

Warning: It is strongly advised not to store your custom scripts within the same folder as Siril built-in scripts.
On Windows, they may get wiped when installing a newer version or prevent correct uninstall. On MacOS, it will
break the bundle and prevent using Siril altogether.
Don't worry, as the list of scripts locations is stored in your configuration file, you should find them back when
installing a newer version.

15.2.2 Troubleshooting

For different reasons, it is possible that the Scripts menu is not visible. This means that the scripts have not been found.
If this is the case, please use the following procedure.
• Click on the Burger icon then on Preferences.
• Click on the Scripts section.
• Delete all the lines in the field Script Storage Directories as shown in the illustration below.
• Click on Apply.
• Close and restart Siril.

286 Chapter 15. Scripts

 Siril, Release 1.2.0

Fig. 1: Script page of preferences. The script are loaded from the paths listed in the Script Storage Directories.

15.2. Populating the list of scripts 287

Siril, Release 1.2.0

15.3 Built-in scripts

All built-in scripts must follow this file structure:

• Mono_Preprocessing.ssf: script for monochrome DSLR or Astro camera preprocessing, uses biases, flats and
darks, registers and stacks the images. To use it: put your files (RAW or FITs) in the folders named lights,
darks, flats and biases (in the Siril default working folder), then run the script.
• OSC_Preprocessing.ssf: same script as above but for One-Shot Color (OSC) DSLR or Astro camera. To use
it: put your files (RAW or FITS) in the folders named lights, darks, flats and biases (in the Siril default
working folder), then run the script.
• OSC_Extract_Ha.ssf: script for OSC DSLR or astro camera preprocessing, for use with Ha filter or dual-band
filter. This script extracts the Ha layer of the color image. To use it: put your files (RAW or FITs) in the folders
named lights, darks, flats and biases (in the Siril default working folder), then run the script.
• OSC_Extract_HaOIII.ssf: same script as above, but extracts Ha and OIII layers of the color image. To use
it: put your files (RAW or FITs) in the folders named lights, darks, flats and biases (in the Siril default
working folder), then run the script. You can also use the menu Image Processing then RGB compositing and
put Ha result in Red channel and OIII result in Green and Blue layers to get an HOO image.

Tip: For owners of SII or SII-OIII dualband filters, the same scripts apply. In fact, it's impossible for a color
sensor to see the difference between Ha (656.3 nm) and SII (671.6 nm), both of which are red.

• RGB_Composition.ssf: This script added in version 1.2 registers monochrome images with a global registration,
reframes them to their common area, and takes the first three images to create a color image. The input images
should be put alone in a directory and named R.fit (or with the configured extension), G.fit and B.fit. The
result will be named rgb.fit. Make sure you remove the process directory between each run.

288 Chapter 15. Scripts

 Siril, Release 1.2.0

Language of scripts

At the beginning of the scripts, and thanks to the contribution of a user, the scripts existed in two versions (English, and
French). When Siril 1.2.0 was released, it was decided to keep only the English scripts for simplicity of maintenance.
We encourage users to distribute translations of the official scripts to their respective communities if they deem it
necessary.

15.4 Getting more scripts

There are a whole bunch of scripts that don't come with Siril installation. However, we've set up a gitlab repository
for them. Everyone is free to register and propose new scripts. We'll accept them according to their relevance: the
language used must be English.
Please refer to this address to browse and download the scripts: https://gitlab.com/free-astro/siril-scripts.

Warning: Keep in mind, however, that these scripts are not necessarily maintained by the users who uploaded
them, and may not be up to date. That said, have fun.

15.5 Writing your own

A script file is a simple text file with the extension *.ssf.

Writing a script is not difficult. It is a succession of calls to commands that will be executed sequentially. Each command
must be executed without returning an error, otherwise the script stops. It is therefore strongly recommended to use the
list of commands to know the syntax and the number of parameters needed. Also, some commands are not scriptable
and are indicated with the icon. It can also be useful to test each script line in the Siril command line.
Each new script created in this way should be placed in a user-defined folder for Siril to find them.

15.4. Getting more scripts 289

Siril, Release 1.2.0

290 Chapter 15. Scripts

 CHAPTER

SIXTEEN

HEADLESS MODE

Siril can both operate with its graphical user interface (GUI) and with a command line interface (CLI) that does not
even require having a display. It can process images for other programs, on remote or embedded computers, using either
scripts or real-time generated operations called commands. The capabilities of the headless Siril are in fact those of
the available commands. There are more than a hundred, allowing preprocessing, processing and photometry analysis
to be done automatically.
Commands can also be used in the GUI version of Siril, either from the embedded command line at the bottom of the
control panel, or with scripts. Scripts are simply a text file containing a list of commands. Reading the scripts page is
recommended before going further.
With the headless version, commands can be executed either by passing a script to run, or by setting the standard input
as a script and writing commands to it, with -s - command line option, or using some named pipes.
Here's an example of bash code calling headless mode, which builds the master-bias and returns its noise to the console
in red:

#!/bin/bash
# bash commands to prepare files

initdir=$(pwd)

######## Set your own variables #############

SCRIPTS_DIRECTORY=$initdir
SIRIL_PATH=siril-cli
#############################################

# Removing process folder if exists #

rm -rf $SCRIPTS_DIRECTORY/process

echo "Running siril bash script in $initdir"

output=$($SIRIL_PATH -d $SCRIPTS_DIRECTORY -s - <<ENDSIRIL

############################################
#
# Example of script that create a master-bias
# and print in red the noise of the image
#
############################################

requires 1.0.0

# Convert Bias Frames to .fit files

(continues on next page)

291
Siril, Release 1.2.0

(continued from previous page)

cd biases
convert bias -out=../process
cd ../process

# Stack Bias Frames to bias_stacked.fit

stack bias rej 3 3 -nonorm -out=master-bias
cd ../..

close
ENDSIRIL
)

log_line=$(echo "$output" | grep -o "log: Background noise value.*")

echo -e "\e[31m$log_line\e[0m"

echo done Siril part

16.1 Command Stream (Pipe)

This mode has been introduced with Siril 0.9.10. Commands can be sent through a named pipe and logs and status can
be obtained through another. The mode is activated using the -p command line argument.
The protocol is quite simple: Siril receives commands and outputs some updates. Only commands that are marked as
scriptable can be used with this system. Whenever the command inputs pipe is closed or the cancel command is given,
the running command is stopped as if the stop button was clicked on in the GUI. The pipes are named siril_command.
in and siril_command.out and are available in /tmp on Unix-based systems. Since version 1.2.0, the paths of the
pipes can be configured with -r and -w options, which allows external programs to create them before starting Siril,
typically with the mkfifo command. Also new in 1.2.0, a ping command will simply give a status return, indicating
if siril is ready to process a command or already busy.
Outputs of siril on the pipe is a stream of one line text and formatted as follows:
• ready is printed on startup, indicating siril is ready to process commands
• log: followed by a log message
• status: verb [subject], where verb can be either of starting, success, error or exit (exit message
is not yet implemented). The subject is the current command name, except for exit that indicates that siril suffered
a fatal error and has to exit.
• progress: value% is the equivalent of the progress bar, it sends percents periodically, and sometimes 0% at
the end of a processing as an idle information.

292 Chapter 16. Headless mode

 CHAPTER

SEVENTEEN

PATH PARSING

Parsing is the ability to parse, i.e. to write strings based on data contained in the FITS header. Path parsing, introduced
in Siril 1.2.0, aims at giving more flexibility to scripting by using header data to write/read filenames or paths. For
now, this is used with the following commands:
• calibrate
• stack and stackall
• all the saveXXX commands
and of course, their GUI counterparts.

17.1 Syntax example

We will take an easy example to begin with. Say you have a file named light_00001.fit and you would like to locate
a masterdark from your masters library that matches the characteristics of said light. As you have chosen a convention
to name your masterdarks, you know that the correct dark should be named something like:

DARK_"exposure"s_G"gain"_O"offset"_T"temperature"C_bin"binning".fit

with the terms between quotes replaced with the values read from your light header. For an exposure of 120s, temper-
ature of -10C, gain/offset of 120/30 and binning 1, the masterdark would be named:

DARK_120s_G120_O30_T-10C_bin1.fit

Well, that's exactly what this feature allows to do. If you specify the dark name with the conventions explained just
after, you can tell Siril to open the light image, read its header and use its values to write such string (and then use it to
calibrate your light).
You can read the info contained in the header either through dumpheader command or by right-clicking on an opened
image and selecting FITS Header.... You would normally get a print like the one below (some keys removed for brevity):

SIMPLE = T / C# FITS
BITPIX = 16 /
NAXIS = 2 / Dimensionality
NAXIS1 = 4144 /
NAXIS2 = 2822 /
BZERO = 32768 /
EXTEND = T / Extensions are permitted
IMAGETYP= 'LIGHT' / Type of exposure
EXPOSURE= 120.0 / [s] Exposure duration
DATE-OBS= '2022-01-24T01:03:34.729' / Time of observation (UTC)
(continues on next page)

293
Siril, Release 1.2.0

(continued from previous page)

XBINNING= 1 / X axis binning factor
YBINNING= 1 / Y axis binning factor
GAIN = 120 / Sensor gain
OFFSET = 30 / Sensor gain offset
INSTRUME= 'ZWO ASI294MC Pro' / Imaging instrument name
SET-TEMP= -10.0 / [degC] CCD temperature setpoint
CCD-TEMP= -10.0 / [degC] CCD temperature
BAYERPAT= 'RGGB' / Sensor Bayer pattern
TELESCOP= '61EDPH' / Name of telescope
FILTER = 'DualBand' / Active filter name
OBJECT = 'Rosette Nebula '/ Name of the object of interest
OBJCTRA = '06 30 36' / [H M S] RA of imaged object
OBJCTDEC= '+04 58 51' / [D M S] Declination of imaged object
RA = 97.6960081674312 / [deg] RA of telescope
DEC = 4.99212765957446 / [deg] Declination of telescope
END

The format used to specify the dark name would then be:

DARK_$EXPTIME:%d$s_G$GAIN:%d$_O$OFFSET:%d$_T$SET-TEMP:%d$C_bin$XBINNING:%d$.fit

All the terms to be parsed are formed as follows: $KEY:fmt$

• KEY is any (valid) key from the light FITS header
• fmt is a format specifier.
For instance, $EXPTIME:%d$ will be parsed to 120 if the light have been exposed for 120s. But would be parsed to
120.0 if you specify $EXPTIME:%0.1f$, thanks to the formatter %x.yf.
The full expression above would therefore evaluate to:

DARK_**120**s_G**120**_O**30**_T**-10**C_bin**1**.fit

In this first example, we have only used conversion to integers with %d. But there are other conventional formatters that
you can use:
• %x.yf for floats
• %s for strings

Note: For strings, leading and trailing spaces are always removed, while spaces within the strings are replaced with _
signs. Example: $OBJECT:%s$ would be converted to Rosette_Nebula.

You can also use some less conventional formatters:

• In order to parse a date from a date-time header key, you can use the special non-standard formatter dm12, which
means date minus 12h. In the header above, the key DATE-OBS has a value of 2022-01-24T01:03:34.729.
$DATE-OBS:dm12$ would convert to 2022-01-23, which was the date at the start of the night. You can also use
special formatter dm0 which will just parse the date, without substracting 12h.
• In order to parse a date-time from a date-time header key, you can use the special non-standard formatter dt,
which just means date-time. In the header above, the key DATE-OBS has a value of 2022-01-24T01:03:34.
729. $DATE-OBS:dt$ would then convert to 2022-01-24_01-03-34.

294 Chapter 17. Path parsing

 Siril, Release 1.2.0

• In order to parse RA and DEC info from OBJCTRA and OBJCTDEC header keys, you can use the special non-standard
formatters ra and dec. In the header above, the keys OBJCTRA and OBJCTDEC have a value of 06 30 36 and
+04 58 51 respectively. $OBJCTRA:ra$_$OBJCTDEC:dec$ would convert to 06h30m36s_+04d58m51s.
• In order to parse RA and DEC info from RA and DEC header keys, when in decimal format, you can use
the special non-standard formatters ran and decn. In the header above, the keys RA and DEC have a value
of 97.6960081674312 and 4.99212765957446 respectively. $RA:ran$_$DEC:decn$ would convert to
06h30m47s_+04d59m32s.
To test the syntax, you can load an image and use the parse command, as reminded below.

Siril command line

parse str [-r]

Parses the string str using the information contained in the header of the image currently loaded. Main purpose of
this command is to debug path parsing of header keys which can be used in other commands.
Option -r specifies the string is to be interpreted in read mode. In read mode, all wilcards defined in string str are
used to find a file name matching the pattern. Otherwise, default mode is write mode and wildcards, if any, are
removed from the string to be parsed.

If str starts with $def prefix, it will be recognized as a reserved keyword and looked for in the strings stored in
gui_prepro.dark_lib, gui_prepro.flat_lib, gui_prepro.bias_lib or gui_prepro.stack_default for $defdark, $defflat,
$defbias or $defstack respectively.
The keyword $seqname$ can also be used when a sequence is loaded

17.2 Finding a file with path parsing

In the example above, we have seen that we could find the name of a masterdark based on the information contained in
the header of the light to be calibrated. This is what is called in the parse command, the read mode.
This behavior is mainly used in conjuction with the calibrate command/tab. In the -dark= option of the command or
in the Dark field of the GUI, you can use the syntax described above. So that you are sure that the matching dark will
be fetched to calibrate the light. The same is equally applicable to Bias and Flat. You can, of course, also give a full
(or relative) path to the file. And the path can also contain expressions of the same kind.
For instance, for flats, you may want to specify the path to a library, which could contain filter or telescope information,
as you may have multiple setups. A path like:

~/astro/masters/flats/$INSTRUME:%s$_$TELESCOP:%s$/$FILTER:%s$/FLAT_bin$XBINNING:%d$.fit

Would then evaluate to:

~/astro/masters/flats/ZWO_ASI294MC_Pro_61EDPH/DualBand/FLAT_bin1.fit

and is a valid value for Flat input.

Of course, if you were to write this as a command in your scripts or in the GUI Flat field every time you calibrate,
that could become a bit tedious. That's when reserved keywords come to the rescue. There are 3 reserved keywords for
masters:

17.2. Finding a file with path parsing 295

Siril, Release 1.2.0

• $defdark
• $defflat
• $defbias
Their values are set in Preferences → Pre-processing section. You can also specify them through scripting thanks to
set command. They correspond to the values of gui_prepro.dark_lib, gui_prepro.flat_lib and gui_prepro.
bias_lib.
When their values are set and you chose to use them as defaults, they will be displayed in the fields of the Calibration
tab. You can also start to write your scripts using these keywords. The calibration step of a new generic script for a
color camera could look like:

calibrate light -dark=$defdark -cc=dark -flat=$defflat -cfa -equalizecfa -debayer

This would pick your masters directly from your libraries and make sure you never mix them up during the calibration
step.

17.3 Writing a file with path parsing

Now, while it is handy to be able to find the files, it would be equally useful to use this syntax to store your files while
stacking. That is exactly what the write mode is about. The syntax can be used in the -out= field of stack and stackall
commands, or in the corresponding field in the GUI.
Let's say you want to write a generic script that prepares your master darks each time you renew your library. In the
stack line of the script, you could write:

stack dark rej 3 3 -nonorm -out=$defdark

This line ensures that the resulting masterdark will be stored at the right location with the correct filename that can then
be fetched to calibrate your lights.
In order to introduce even more flexibility with the stack commands, there are two more reserved keywords:
• $defstack
• $sequencename$
As for default masters, $defstack is configured in the same section of the Preferences, or with a set command on
gui_prepro.stack_default. For instance, let's assume you have defined $defstack as:

Result_$OBJECT:%s$_$DATE-OBS:dm12$_$LIVETIME:%d$s

The script line:

stack r_pp_light rej 3 3 -norm=addscale -output_norm -out=$defstack

would save the stack result as:

Result_Rosette_Nebula_2022-01-24_12000s.fit

As of Siril 1.2.0, the default name for stacking is defined as $sequencename$stacked (the _ sign is added if not
present). This is similar to the behavior in previous versions, except it is now explicit that pathparsing is used.

296 Chapter 17. Path parsing

 Siril, Release 1.2.0

17.4 Using wildcards

It could be that you want to use some key value in your masters name that do not match the key value in the frames
to be calibrated. With an example, it may be a bit clearer. Say, you want, in your masterflats names, to keep record of
their exposure time. Something like:

FLAT_1.32s_Halpha_G120_O30_bin1.fit

If you put a field $EXPTIME:%0.2f$ in $defflat, it will end up with an error at calibration step. Simply because the
EXPTIME key will be read from the light frame to be calibrated, not a flat.
To deal with this situation, you can use wildcards in the expressions to be parsed:

FLAT_$*EXPTIME:%0.2f$_$FILTER:%s$_G$GAIN:%d$_O$OFFSET:%d$_bin$XBINNING:%d$

Note the * symbol placed right before EXPTIME.

What this symbol means is the following:
• In write mode, so basically when stacking your masterflat, the field EXPOSURE will be used to form the filename
to be saved. In the example above, you would then effectively save to FLAT_1.32s_Halpha_G120_O30_bin1.
fit.
• In read mode, so when calibrating your lights, the field EXPOSURE will be replaced by *. When searching for
such file, Siril will fetch all the files that marches the pattern FLAT_*_Halpha_G120_O30_bin1.fit. Hopefully,
your naming convention is robust enough so that it finds only one matching file and uses it to calibrate.

Warning: In the event Siril finds more than one file in read mode, it will emit a warning in the console and select
the most recent file. As it may not produce the desired outcome, you should reconsider your naming convention if
this happens.

17.4. Using wildcards 297

Siril, Release 1.2.0

298 Chapter 17. Path parsing

 CHAPTER

EIGHTEEN

LIVESTACKING

Live Stacking is a technique in astrophotography that allows the real-time stacking of a series of images to produce
a higher quality image. Unlike traditional image stacking, which involves combining multiple images after they have
been captured, live stacking combines the images as they are being captured. This can provide an instant preview of the
final image and allow the astrophotographer to make adjustments in real-time to improve the quality of the final result.
Siril 1.2.0 includes this feature, which however is experimental for the moment. It allows to monitor a file in real time
and to stack the images that arrive as they come in. Stacking of images can be done with and without Dark/Bias/Flats.
The latter must be done beforehand if you want to use them.

18.1 Livestacking (GUI)

Note: Only FITS and RAW camera images are compatible with livestacking.

To start livestacking you need to :

• Define a working directory, with the home button, in which the photos will arrive one after the other.
• Click on the framed button on the image below.

A new window pops up.

This window contains several buttons and options. A play button, which when clicked becomes a pause button, and a
stop button. The first one allows to start or pause the monitoring of the working directory, and the last one to stop it.
All other options are fairly standard in the preprocessing of astronomical images:
• debayer: The Bayer matrix is detected in files and debayer is automatically enabled. This is more of an indicator
than an option.
• use 32 bits: Use 32 bits for image processing. This is slower and generally useless in terms of quality for live
stacking.
• remove gradient: Apply a linear background gradient removal on calibrated input frames.
• shift-only registration: Only shift images instead of using rotation on registration. This should be unchecked
for alt-az or heavily drifting mounts. This makes one image processing much faster.
The 3 sections below provide the information necessary for the user to follow the evolution of the stack.
• Statistics: This session gives the evolution of the noise level in ADU as well as the image processing time.

299
Siril, Release 1.2.0

• Stacking: This section summarizes the number of images stacked and the cumulative exposure time.
• Configuration is a section that is not expanded by default. Once it is done, the frame gives details if the prepro-
cessing is done using master files and the type of alignment and stacking.

Note: To use master files during a livestacking session, you must first have stacked your files. Then, once done and
before launching the session, please load them in the Calibration tab. They will then be taken into account in the
livestacking, and visible in the Configuration part of the livestack dialog.

18.2 Livestacking (Headless)

It is possible to use livestacking from the command line. For this, only 3 commands are necessary and explained below.
• The first, start_ls starts the livestacking session. It is possible to provide it with darks and flats images as argu-
ments in order to calibrate the images during livestacking.

Siril command line

300 Chapter 18. Livestacking

 Siril, Release 1.2.0

start_ls [-dark=filename] [-flat=filename] [-rotate] [-32bits]

Initializes a livestacking session, using the optional calibration files and waits for input files to be provided by
the LIVESTACK command until STOP_LS is called. Default processing will use shift-only registration and
16-bit processing because it's faster, it can be changed to rotation with -rotate and -32bits

Note that the live stacking commands put Siril in a state in which it's not able to process other commands. After
START_LS, only LIVESTACK, STOP_LS and EXIT can be called until STOP_LS is called to return Siril in its
normal, non-live-stacking, state

Links: livestack, stop_ls, exit

• The livestack command is to be applied to each image you wish to stack.

Siril command line

livestack filename

Process the provided image for live stacking. Only possible after START_LS. The process involves calibrating
the incoming file if configured in START_LS, demosaicing if it's an OSC image, registering and stacking. The
temporary result will be in the file live_stack_00001.fit until a new option to change it is added

Links: start_ls

• Finally, the stop_ls command stops the livestacking session.

Siril command line

stop_ls

Stops the live stacking session. Only possible after START_LS

Links: start_ls

18.2. Livestacking (Headless) 301

Siril, Release 1.2.0

302 Chapter 18. Livestacking

 CHAPTER

NINETEEN

COMMANDS

The following page lists all the commands available in Siril 1.2.0.

You can access an index by clicking this icon .

Commands marked with this icon can be used in scripts while those marked with this one cannot.

Tip: For all the sequence commands, you can replace argument sequencename with a . if the sequence to be processed
is already loaded.

Tip: If you want to provide an argument that includes a string with spaces, for example a filename, you need to quote
the entire argument not just the string. So for example you should use command "-filename=My File.fits", not
command -filename="My File.fits".

addmax

addmax filename

Computes a new image combining the image in memory with the image filename. At each pixel location, the new
value is determined as the max of value in current image and in filename

asinh

asinh [-human] stretch [offset]

Stretches the image to show faint objects using an hyperbolic arcsin transformation. The mandatory argument
stretch, typically between 1 and 1000, will give the strength of the stretch. The black point can be offset by providing
an optional offset argument in the normalized pixel value of [0, 1]. Finally the option -human enables using human
eye luminous efficiency weights to compute the luminance used to compute the stretch value for each pixel, instead of
the simple mean of the channels pixel values. This stretch method preserves lightness from the L*a*b* color space

303
Siril, Release 1.2.0

autoghs

autoghs [-linked] shadowsclip stretchamount [-b=] [-hp=] [-lp=]

Application of the generalized hyperbolic stretch with a symmetry point SP defined as k.sigma from the median of
each channel (the provided shadowsclip value is the k here and can be negative). By default, SP and the stretch are
computed per channel; SP can be computed as a mean of image channels by passing -linked. The stretch amount D is
provided in the second mandatory argument.
Implicit values of 13 for B, making it very focused on the SP brightness range, 0.7 for HP, 0 for LP are used but can
be changed with the options of the same names

autostretch

autostretch [-linked] [shadowsclip [targetbg]]

Auto-stretches the currently loaded image, with different parameters for each channel (unlinked) unless -linked is
passed. Arguments are optional, shadowclip is the shadows clipping point, measured in sigma units from the main
histogram peak (default is -2.8), targetbg is the target background value, giving a final brightness to the image, range
[0, 1], default is 0.25. The default values are those used in the Auto-stretch rendering from the GUI.

Do not use the unlinked version after color calibration, it will alter the white balance

bg

bg

Returns the background level of the loaded image

bgnoise

bgnoise

304 Chapter 19. Commands

 Siril, Release 1.2.0

Returns the background noise level of the loaded image

binxy

binxy coefficient [-sum]

Computes the numerical binning of the in-memory image (sum of the pixels 2x2, 3x3..., like the analogic binning of
CCD camera). If the optional argument -sum is passed, then the sum of pixels is computed, while it is the average
when no optional argument is provided

boxselect

boxselect [-clear] [x y width height]

Make a selection area in the currently loaded image with the arguments x, y, width and height, with x and y being
the coordinates of the top left corner starting at (0, 0), and width and height, the size of the selection. The -clear
argument deletes any selection area. If no argument is passed, the current selection is printed

calibrate

calibrate sequencename [-bias=filename] [-dark=filename] [-flat=filename] [-cc=dark␣

˓→[siglo sighi] || -cc=bpm bpmfile] [-cfa] [-debayer] [-fix_xtrans] [-equalize_cfa] [-

˓→opt] [-all] [-prefix=] [-fitseq]

Calibrates the sequence sequencename using bias, dark and flat given in argument.

For bias, a uniform level can be specified instead of an image, by entering a quoted expression starting with an = sign,
such as -bias="=256" or -bias="=64*$OFFSET".

By default, cosmetic correction is not activated. If you wish to apply some, you will need to specify it with -cc=
option.
You can use -cc=dark to detect hot and cold pixels from the masterdark (a masterdark must be given with the -dark=
option), optionally followed by siglo and sighi for cold and hot pixels respectively. A value of 0 deactivates the
correction. If sigmas are not provided, only hot pixels detection with a sigma of 3 will be applied.
Alternatively, you can use -cc=bpm followed by the path to your Bad Pixel Map to specify which pixels must be
corrected. An example file can be obtained with a find_hot command on a masterdark.

305
Siril, Release 1.2.0

Three options apply to color images (in CFA format): -cfa for cosmetic correction purposes, -debayer to demosaic
images before saving them, and -equalize_cfa to equalize the mean intensity of RGB layers of the master flat, to avoid
tinting the calibrated image.
The -fix_xtrans option is dedicated to X-Trans images by applying a correction on darks and biases to remove a
rectangle pattern caused by autofocus.
It is also possible to optimize the dark subtraction with -opt, which requires both bias and dark masters to be provided.
By default, frames marked as excluded will not be processed. The argument -all can be used to force processing of all
frames even if marked as excluded.
The output sequence name starts with the prefix "pp_" unless otherwise specified with option -prefix=.
If -fitseq is provided, the output sequence will be a FITS sequence (single file)

calibrate_single

calibrate_single imagename [-bias=filename] [-dark=filename] [-flat=filename] [-cc=dark␣

˓→[siglo sighi] || -cc=bpm bpmfile] [-cfa] [-debayer] [-fix_xtrans] [-equalize_cfa] [-

˓→opt] [-prefix=]

Calibrates the image imagename using bias, dark and flat given in argument.

For bias, a uniform level can be specified instead of an image, by entering a quoted expression starting with an = sign,
such as -bias="=256" or -bias="=64*$OFFSET".

By default, cosmetic correction is not activated. If you wish to apply some, you will need to specify it with -cc=
option.
You can use -cc=dark to detect hot and cold pixels from the masterdark (a masterdark must be given with the -dark=
option), optionally followed by siglo and sighi for cold and hot pixels respectively. A value of 0 deactivates the
correction. If sigmas are not provided, only hot pixels detection with a sigma of 3 will be applied.
Alternatively, you can use -cc=bpm followed by the path to your Bad Pixel Map to specify which pixels must be
corrected. An example file can be obtained with a find_hot command on a masterdark.

Three options apply to color images (in CFA format): -cfa for cosmetic correction purposes, -debayer to demosaic
images before saving them, and -equalize_cfa to equalize the mean intensity of RGB layers of the master flat, to avoid
tinting the calibrated image.
The -fix_xtrans option is dedicated to X-Trans images by applying a correction on darks and biases to remove a
rectangle pattern caused by autofocus.
It is also possible to optimize the dark subtraction with -opt, which requires both bias and dark masters to be provided.
The output filename starts with the prefix "pp_" unless otherwise specified with option -prefix=

capabilities

306 Chapter 19. Commands

 Siril, Release 1.2.0

capabilities

Lists Siril capabilities, based on compilation options and runtime

catsearch

catsearch name

Searches an object by name and adds it to the user annotation catalog. The object is first searched in the annotation
catalogs, if not found a request is made to SIMBAD.
The object can be a solar system object, in that case the prefix 'a:' for asteroid, 'p:' for planet or 'c:' for comet is needed,
and the search is done for the date and Earth location found in the image's header, using the IMCCE Miriade service

cd

cd directory

Sets the new current working directory.

The argument directory can contain the ~ token, expanded as the home directory, directories with spaces in the name
can be protected using single or double quotes

cdg

cdg

Returns the coordinates of the center of gravity of the image. Only pixels with values above 15.7% of max ADU and
having four neighbors filling the same condition are used to compute it, and it is computed only if there are at least 50
of them

307
Siril, Release 1.2.0

clahe

clahe cliplimit tileSize

Equalizes the histogram of an image using Contrast Limited Adaptive Histogram Equalization.

cliplimit sets the threshold for contrast limiting.

tilesize sets the size of grid for histogram equalization. Input image will be divided into equally sized rectangular tiles

clear

clear

Clears the graphical output logs

clearstar

clearstar

Clears all the stars saved in memory and displayed on the screen

close

close

Properly closes the opened image and the opened sequence, if any

convert

convert basename [-debayer] [-fitseq] [-ser] [-start=index] [-out=]

308 Chapter 19. Commands

 Siril, Release 1.2.0

Converts all images of the current working directory that are in a supported format into Siril's sequence of FITS
images (several files) or a FITS sequence (single file) if -fitseq is provided or a SER sequence (single file) if -ser is
provided. The argument basename is the base name of the new sequence, numbers and the extension will be put
behind it.
For FITS images, Siril will try to make a symbolic link; if not possible, files will be copied. The option -debayer
applies demosaicing to CFA input images; in this case no symbolic link is done.
-start=index sets the starting index number, useful to continue an existing sequence (not used with -fitseq or -ser;
make sure you remove or clear the target .seq if it exists in that case).
The -out= option changes the output directory to the provided argument.

See also CONVERTRAW and LINK

Links: convertraw, link

convertraw

convertraw basename [-debayer] [-fitseq] [-ser] [-start=index] [-out=]

Same as CONVERT but converts only DSLR RAW files found in the current working directory

Links: convert

cosme

cosme [filename].lst

Applies the local mean to a set of pixels on the loaded image (cosmetic correction). The coordinates of these pixels
are in a text file [.lst file], the FIND_HOT command can also create it for single hot pixels, but manual operation is
needed to remove rows or columns. COSME is adapted to correct residual hot and cold pixels after calibration.
Instead of providing the list of bad pixels, it's also possible to detect them in the current image using the
FIND_COSME command

Links: find_hot, find_cosme

cosme_cfa

309
Siril, Release 1.2.0

cosme_cfa [filename].lst

Same function as COSME but applying to RAW CFA images

Links: cosme

crop

crop [x y width height]

Crops to a selected area of the loaded image.

If a selection is active, no further arguments are required. Otherwise, or in scripts, arguments have to be given, with x
and y being the coordinates of the top left corner, and width and height the size of the selection. Alternatively, the
selection can be made using the BOXSELECT command

Links: boxselect

ddp

ddp level coef sigma

Performs a DDP (digital development processing) on the loaded image, as described first by Kunihiko Okano. This
implementation is the one described in IRIS.

It combines a linear distribution on low levels (below level) and a non-linear one on high levels.
It uses a Gaussian filter of standard deviation sigma and multiplies the resulting image by coef. Typical values for
sigma are within 0.7 and 2. The level argument should be in the range [0, 65535] for 16-bit images and may be given
either in the range [0, 1] or [0, 65535] for 32-bit images in which case it will be scaled automatically

denoise

denoise [-nocosmetic] [-mod=m] [ -vst | -da3d | -sos=n [-rho=r] ] [-indep]

310 Chapter 19. Commands

 Siril, Release 1.2.0

Denoises the image using the non-local Bayesian algorithm described by Lebrun, Buades and Morel.

It is strongly recommended to apply cosmetic correction to remove salt and pepper noise before running denoise, and
by default this command will apply cosmetic correction automatically. However, if this has already been carried out
earlier in the workflow it may be disabled here using the optional command -nocosmetic.

An optional argument -mod=m may be given, where 0 <= m <= 1. The output pixel is computed as : out=m x d + (1
m) x in, where d is the denoised pixel value. A modulation value of 1 will apply no modulation. If the parameter is
omitted, it defaults to 1.

The optional argument -vst can be used to apply the generalised Anscombe variance stabilising transform prior to
NL-Bayes. This is useful with photon-starved images such as single subs, where the noise follows a Poisson or
Poisson-Gaussian distribution rather than being primarily Gaussian. It cannot be used in conjunction with DA3D or
SOS, and for denoising stacked images it is usually not beneficial.

The optional argument -da3d can be used to enable Data-Adaptive Dual Domain Denoising (DA3D) as a final stage
denoising algorithm. This uses the output of BM3D as a guide image to refine the denoising. It improves detail and
reduces staircasing artefacts.

The optional argument -sos=n can be used to enable Strengthen-Operate-Subtract (SOS) iterative denoise boosting,
with the number of iterations specified by n. In particular, this booster may produce better results if the un-boosted
NL-Bayes algorithm produces artefacts in background areas. If both -da3d and -sos=n are specified, the last to be
specified will apply.

The optional argument -rho=r may be specified, where 0 < r < 1. This is used by the SOS booster to determine the
amount of noisy image added in to the intermediate result between each iteration. If -sos=n is not specified then the
parameter is ignored.

The default is not to apply DA3D or SOS, as the improvement in denoising is usually relatively small and these
techniques requires additional processing time.

In very rare cases, blocky coloured artefacts may be found in the output when denoising colour images. The optional
argument -indep can be used to prevent this by denoising each channel separately. This is slower but will eliminate
artefacts

dir

dir

Lists files and directories in the working directory

This command is only available on Microsoft Windows, for the equivalent command on Linux and MacOS, see ls.

311
Siril, Release 1.2.0

dumpheader

dumpheader

Dumps the FITS header of the loaded image in the console

entropy

entropy

Computes the entropy of the loaded image on the displayed layer, only in the selected area if one has been selected or
in the whole image. The entropy is one way of measuring the noise or the details in an image

exit

exit

Quits the application

extract

extract NbPlans

Extracts NbPlans planes of wavelet domain of the loaded image.

See also WAVELET and WRECONS. For color extraction, see SPLIT

Links: wavelet, wrecons, split

312 Chapter 19. Commands

 Siril, Release 1.2.0

extract_Green

extract_Green

Extracts green signal from the loaded CFA image. It reads the Bayer matrix information from the image or the
preferences and exports only the averaged green filter data as a new half-sized FITS file. A new file is created, its
name is prefixed with "Green_"

extract_Ha

extract_Ha

Extracts H-Alpha signal from the loaded CFA image. It reads the Bayer matrix information from the image or the
preferences and exports only the red filter data as a new half-sized FITS file. A new file is created, its name is prefixed
with "Ha_"

extract_HaOIII

extract_HaOIII [-resample=]

Extracts H-Alpha and O-III signals from the loaded CFA image. It reads the Bayer matrix information from the image
or the preferences and exports only the red filter data for H-Alpha as a new half-sized FITS file (like EXTRACTHA)
and keeps the three others for O-III with an interpolated replacement for the red pixel. The output files names start
with the prefix "Ha_" and "OIII_"

The optional argument -resample={ha|oiii} sets whether to upsample the Ha image or downsample the OIII image to
have images the same size. If this argument is not provided, no resampling will be carried out and the OIII image will
have twice the height and width of the Ha image

fdiv

fdiv filename scalar

Divides the loaded image by the image given in argument. The resulting image is multiplied by the value of the
scalar argument. See also IDIV

313
Siril, Release 1.2.0

Links: idiv

ffill

ffill value [x y width height]

Same command as FILL but this is a symmetric fill of a region defined by the mouse or with BOXSELECT. Used to
process an image in the Fourier (FFT) domain

Links: fill, boxselect

fftd

fftd modulus phase

Applies a Fast Fourier Transform to the loaded image. modulus and phase given in argument are the names of the
saved in FITS files

ffti

ffti modulus phase

Retrieves corrected image applying an inverse transformation. The modulus and phase arguments are the input file
names, the result will be the new loaded image

fill

fill value [x y width height]

314 Chapter 19. Commands

 Siril, Release 1.2.0

Fills the loaded image entirely or only the selection if there is one with pixels having the value intensity expressed in
ADU

find_cosme

find_cosme cold_sigma hot_sigma

Applies an automatic detection and replacement of cold and hot pixels in the loaded image, with the thresholds
passed in arguments in sigma units

find_cosme_cfa

find_cosme_cfa cold_sigma hot_sigma

Same command as FIND_COSME but for CFA images

Links: find_cosme

find_hot

find_hot filename cold_sigma hot_sigma

Saves a list file filename (text format) in the working directory which contains the coordinates of the pixels which
have an intensity hot_sigma times higher and cold_sigma lower than standard deviation, extracted from the loaded
image. We generally use this command on a master-dark file. The COSME command can apply this list of bad pixels
to a loaded image, see also SEQCOSME to apply it to a sequence

Links: cosme, seqcosme

Lines P x y type will fix the pixel at coordinates (x, y) type is an optional character (C or H) specifying to Siril if
the current pixel is cold or hot. This line is created by the command FIND_HOT but you also can add some lines
manually:
Lines C x 0 type will fix the bad column at coordinates x.
Lines L y 0 type will fix the bad line at coordinates y.

315
Siril, Release 1.2.0

findstar

findstar [-out=] [-layer=] [-maxstars=]

Detects stars in the currently loaded image, having a level greater than a threshold computed by Siril.
After that, a PSF is applied and Siril rejects all detected structures that don't fulfill a set of prescribed detection
criteria, that can be tuned with command SETFINDSTAR.
Finally, an ellipse is drawn around detected stars.

Optional parameter -out= allows the results to be saved to the given path.
Option -layer= specifies the layer onto which the detection is performed (for color images only).
You can also limit the maximum number of stars detected by passing a value to option -maxstars=.

See also CLEARSTAR

Links: psf , setfindstar, clearstar

fix_xtrans

fix_xtrans

Fixes the Fujifilm X-Trans Auto Focus pixels in the loaded image.

Indeed, because of the phase detection auto focus system, the photosites used for auto focus get a little less light than
the surrounding photosites. The camera compensates for this and increases the values from these specific photosites
giving a visible square in the middle of the dark/bias frames

fixbanding

fixbanding amount sigma [-vertical]

Tries to remove the horizontal or vertical banding in the loaded image.

amount defines the amount of correction, between 0 and 4.
sigma defines the highlight protection level of the algorithm, higher sigma gives higher protection, between 0 and 5.
Values of 1 and 1 are often good enough.

316 Chapter 19. Commands

 Siril, Release 1.2.0

-vertical option enables to perform vertical banding removal, horizontal is the default

fmedian

fmedian ksize modulation

Performs a median filter of size ksize x ksize (ksize MUST be odd) to the loaded image with a modulation parameter
modulation.

The output pixel is computed as : out=mod x m + (1 mod) x in, where m is the median-filtered pixel value. A
modulation's value of 1 will apply no modulation

fmul

fmul scalar

Multiplies the loaded image by the scalar given in argument

gauss

gauss sigma

Applies to the loaded image a Gaussian blur with the given sigma.

See also UNSHARP, the same with a blending parameter

Links: unsharp

get

get { -a | -A | variable }

317
Siril, Release 1.2.0

Gets a value from the settings using its name, or list all with -a (name and value list) or with -A (detailed list)

See also SET to update values

Links: set

getref

getref sequencename

Prints information about the reference image of the sequence given in argument. First image has index 0

ght

ght -D= [-B=] [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat] [channels]

Generalised hyperbolic stretch based on the work of the ghsastro.co.uk team.

The argument -D= defines the strength of the stretch, between 0 and 10. This is the only mandatory argument. The
following optional arguments further tailor the stretch:
B defines the intensity of the stretch near the focal point, between -5 and 15;
LP defines a shadow preserving range between 0 and SP where the stretch will be linear, preserving shadow detail;
SP defines the symmetry point of the stretch, between 0 and 1, which is the point at which the stretch will be most
intense;
HP defines a region between HP and 1 where the stretch is linear, preserving highlight details and preventing star
bloat.
If omitted B, LP and SP default to 0.0 ad HP defaults to 1.0.
An optional argument (either -human, -even or -independent) can be passed to select either human-weighted or
even-weighted luminance or independent colour channels for colour stretches. The argument is ignored for mono
images. Alternatively, the argument -sat specifies that the stretch is performed on image saturation - the image must
be color and all channels must be selected for this to work.
Optionally the parameter [channels] may be used to specify the channels to apply the stretch to: this may be R, G, B,
RG, RB or GB. The default is all channels

grey_flat

318 Chapter 19. Commands

 Siril, Release 1.2.0

grey_flat

Equalizes the mean intensity of RGB layers in the loaded CFA image. This is the same process used on flats during
calibration when the option equalize CFA is used

help

help [command]

Lists the available commands or help for one command

histo

histo channel (channel=0, 1, 2 with 0: red, 1: green, 2: blue)

Calculates the histogram of the layer of the loaded image and produces file histo_[channel name].dat in the working
directory.
layer = 0, 1 or 2 with 0=red, 1=green and 2=blue

iadd

iadd filename

Adds the image filename to the loaded image.

Result will be in 32 bits per channel if allowed in the preferences

idiv

idiv filename

319
Siril, Release 1.2.0

Divides the loaded image by the image filename.

Result will be in 32 bits per channel if allowed in the preferences.

See also FDIV

Links: fdiv

imul

imul filename

Multiplies image filename by the loaded image.

Result will be in 32 bits per channel if allowed in the preferences

inspector

inspector

Splits the loaded image in a nine-panel mosaic showing the image corners and the center for a closer inspection (GUI
only)

invght

invght -D= [-B=] [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat] [channels]

Inverts a generalised hyperbolic stretch. It provides the inverse transformation of GHT, if provided with the same
parameters, undoes a GHT command, possibly returning to a linear image. It can also work the same way as GHT but
for images in negative

Links: ght

invmodasinh

320 Chapter 19. Commands

 Siril, Release 1.2.0

invmodasinh -D= [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat] [channels]

Inverts a modified arcsinh stretch. It provides the inverse transformation of MODASINH, if provided with the same
parameters, undoes a MODASINH command, possibly returning to a linear image. It can also work the same way as
MODASINH but for images in negative

Links: modasinh

invmtf

invmtf low mid high [channels]

Inverts a midtones transfer function. It provides the inverse transformation of MTF, if provided with the same
parameters, undoes a MTF command, possibly returning to a linear image. It can also work the same way as MTF but
for images in negative

Links: mtf

isub

isub filename

Subtracts the loaded image by the image filename.

Result will be in 32 bits per channel if allowed in the preferences, so capable of storing negative values. To clip
negative value, use 16 bit mode or use the THRESHLO command

Links: threshlo

jsonmetadata

jsonmetadata FITS_file [-stats_from_loaded] [-nostats] [-out=]

Dumps metadata and statistics of the currently loaded image in JSON form. The file name is required, even if the
image is already loaded. Image data may not be read from the file if it is the current loaded image and if the

321
Siril, Release 1.2.0

-stats_from_loaded option is passed. Statistics can be disabled by providing the -nostats option. A file containing
the JSON data is created with default file name '$(FITS_file_without_ext).json' and can be changed with the -out=
option

light_curve

light_curve sequencename channel [-autoring] { -at=x,y | -wcs=ra,dec } { -refat=x,y | -

˓→refwcs=ra,dec } ...

light_curve sequencename channel [-autoring] -ninastars=file

Analyses several stars with aperture photometry in a sequence of images and produces a light curve for one,
calibrated by the others. The first coordinates, in pixels if -at= is used or in degrees if -wcs= is used, are for the star
whose light will be plotted, the others for the comparison stars.
Alternatively, a list of target and reference stars can be passed in the format of the NINA exolpanet plugin star list,
with the -ninastars= option. Siril will verify that all reference stars can be used before actually using them. A data
file is created in the current directory named light_curve.dat, gnuplot plots the result to a PNG image if available
The ring radii for aperture photometry can either be configured in the settings or set to a factor of the reference
image's FWHM if -autoring is passed.

See also SEQPSF for operations on single star

Links: seqpsf

linear_match

linear_match reference low high

Computes and applies a linear function between a reference image and the loaded image.

The algorithm will ignore all reference pixels whose values are outside of the [low, high] range

link

link basename [-start=index] [-out=]

322 Chapter 19. Commands

 Siril, Release 1.2.0

Same as CONVERT but converts only FITS files found in the current working directory. This is useful to avoid
conversions of JPEG results or other files that may end up in the directory

Links: convert

linstretch

linstretch -BP= [-sat] [channels]

Stretches the image linearly to a new black point BP.

The argument [channels] may optionally be used to specify the channels to apply the stretch to: this may be R, G, B,
RG, RB or GB. The default is all channels.
Optionally the parameter -sat may be used to apply the linear stretch to the image saturation channel. This argument
only works if all channels are selected

livestack

livestack filename

Process the provided image for live stacking. Only possible after START_LS. The process involves calibrating the
incoming file if configured in START_LS, demosaicing if it's an OSC image, registering and stacking. The temporary
result will be in the file live_stack_00001.fit until a new option to change it is added

Links: start_ls

load

load filename[.ext]

Loads the image filename from the current working directory, which becomes the 'currently loaded image' used in
many of the single-image commands.
It first attempts to load filename, then filename.fit, filename.fits and finally all supported formats.
This scheme is applicable to every Siril command that involves reading files

323
Siril, Release 1.2.0

log

log

Computes and applies a logarithmic scale to the loaded image, using the following formula: log(1 - (value - min) /
(max - min)), with min and max being the minimum and maximum pixel value for the channel

ls

ls

Lists files and directories in the working directory

This command is only available on Unix-like Systems, for the equivalent command on Microsoft Windows, see dir.

makepsf

makepsf clear
makepsf load filename
makepsf save [filename]
makepsf blind [-l0] [-si] [-multiscale] [-lambda=] [-comp=] [-ks=] [-savepsf=]
makepsf stars [-sym] [-ks=] [-savepsf=]
makepsf manual { -gaussian | -moffat | -disc | -airy } [-fwhm=] [-angle=] [-ratio=] [-
˓→beta=] [-dia=] [-fl=] [-wl=] [-pixelsize=] [-obstruct=] [-ks=] [-savepsf=]

Generates a PSF for use with deconvolution, any of the three methods exposed by RL, SB or WIENER commands.
One of the following must be given as the first argument: clear (clears the existing PSF), load (loads a PSF from a
file), save (saves the current PSF), blind (blind estimate of tke PSF), stars (generates a PSF based on measured stars
from the image) or manual (generates a PSF manually based on a function and parameters).

No additional arguments are required when using the clear argument.

To load a previously saved PSF the load argument requires the PSF filename as a second argument. This may be in
any format that Siril has been compiled with support for, but it must be square and should ideally be odd.

To save a previously generated PSF the argument save is used. Optionally, a filename may be provided (this must
have one of the extensions ".fit", ".fits", ".fts" or ".tif") but if none is provided the PSF will be named based on the
name of the open file or sequence.

324 Chapter 19. Commands

 Siril, Release 1.2.0

For blind, the following optional arguments may be provided: -l0 uses the l0 descent method, -si uses the spectral
irregularity method, -multiscale configures the l0 method to do a multi-scale PSF estimate, -lambda= provides the
regularization constant.

For PSF from detected stars the only optional parameter is -sym, which configures the PSF to be symmetric.

For a manual PSF, one of -gaussian, -moffat, -disc or -airy can be provided to specify the PSF function, Gaussian
by default. For Gaussian or Moffat PSFs the optional arguments -fwhm=, -angle= and -ratio= may be provided. For
Moffat PSFs the optional argument -beta= may also be provided. If these values are omitted, they default to the same
values as in the deconvolution dialog. For disc PSFs only the argument -fwhm= is required, which for this function is
used to set the diameter of the PSF. For Airy PSFs the following arguments may be provided: -dia= (sets the
telescope diameter), -fl= (sets the telescope focal length), -wl= (sets the wavelength to calculate the Airy diffraction
pattern for), -pixelsize= (sets the sensor pixel size), -obstruct= (sets the central obstruction as a percentage of the
overall aperture area). If these parameters are not provided, wavelength will default to 525nm and central obstruction
will default to 0%. Siril will attempt to read the others from the open image, but some imaging software may not
provide all of them in which case you will get bad results, and note the metadata may not be populated for SER format
videos. You will learn from experience which are safe to omit for your particular imaging setup.

For any of the above PSF generation options the optional argument -ks= may be provided to set the PSF dimension,
and the optional argument -savepsf=filename may be used to save the generated PSF: a filename must be provided
and the same filename extension requirements apply as for makepsf save filename

Links: psf , rl, sb, wiener

merge

merge sequence1 sequence2 [sequence3 ...] output_sequence

Merges several sequences of the same type (FITS images, FITS sequence or SER) and same image properties into a
new sequence with base name newseq created in the current working directory, with the same type. The input
sequences can be in different directories, can specified either in absolute or relative path, with the exact .seq name or
with only the base name with or without the trailing '_'

merge_cfa

merge_cfa file_CFA0 file_CFA1 file_CFA2 file_CFA3 bayerpattern

Builds a Bayer masked colour image from 4 separate images containing the data from Bayer subchannels CFA0,
CFA1, CFA2 and CFA3. (The corresponding command to split the CFA pattern into subchannels is split_cfa.) This
function can be used as part of a workflow applying some processing to the individual Bayer subchannels prior to

325
Siril, Release 1.2.0

demosaicing. The fifth parameter bayerpattern specifies the Bayer matrix pattern to recreate: bayerpattern should
be one of 'RGGB', 'BGGR', 'GRBG' or 'GBRG'

mirrorx

mirrorx [-bottomup]

Flips the loaded image about the horizontal axis. Option -bottomup will only flip it if it's not already bottom-up

mirrorx_single

mirrorx_single image

Flips the image about the horizontal axis, only if needed (if it's not already bottom-up). It takes the image file name as
argument, allowing it to avoid reading image data entirely if no flip is required. Image is overwritten if a flip is made

mirrory

mirrory

Flips the image about the vertical axis

modasinh

modasinh -D= [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat] [channels]

Modified arcsinh stretch based on the work of the ghsastro.co.uk team.

The argument -D= defines the strength of the stretch, between 0 and 10. This is the only mandatory argument. The
following optional arguments further tailor the stretch:
LP defines a shadow preserving range between 0 and SP where the stretch will be linear, preserving shadow detail;

326 Chapter 19. Commands

 Siril, Release 1.2.0

SP defines the symmetry point of the stretch, between 0 and 1, which is the point at which the stretch will be most
intense;
HP defines a region between HP and 1 where the stretch is linear, preserving highlight details and preventing star
bloat.
If omitted LP and SP default to 0.0 ad HP defaults to 1.0.
An optional argument (either -human, -even or -independent) can be passed to select either human-weighted or
even-weighted luminance or independent colour channels for colour stretches. The argument is ignored for mono
images. Alternatively, the argument -sat specifies that the stretch is performed on image saturation - the image must
be color and all channels must be selected for this to work.
Optionally the parameter [channels] may be used to specify the channels to apply the stretch to: this may be R, G, B,
RG, RB or GB. The default is all channels

mtf

mtf low mid high [channels]

Applies midtones transfer function to the current loaded image.

Three parameters are needed, low, midtones and high where midtones balance parameter defines a nonlinear
histogram stretch in the [0,1] range. For an automatic determination of the parameters, see AUTOSTRETCH.
Optionally the parameter [channels] may be used to specify the channels to apply the stretch to: this may be R, G, B,
RG, RB or GB. The default is all channels

Links: autostretch

neg

neg

Changes pixel values of the currently loaded image to a negative view, like 1-value for 32 bits, 65535-value for 16
bits. This does not change the display mode

new

new width height nb_channel

327
Siril, Release 1.2.0

Creates a new image filled with zeros with a size of width x height.

The image is in 32-bit format, and it contains nb_channel channels, nb_channel being 1 or 3. It is not saved, but
becomes the loaded image and it is displayed and can be saved afterwards

nomad

nomad [limit_magnitude] [-catalog=] [-photo]

Displays stars from the local catalog by default, for the loaded plate solved image, in GUI only, down to the provided
limit_magnitude (13 by default).
An alternate online catalog can be specified with -catalog=, taking values tycho2, nomad, gaia, ppmxl, brightstars,
apass.
Stars with no B-V information will be kept; they can be excluded by passing -photo

nozero

nozero level

Replaces null values by level values. Useful before an idiv or fdiv operation, mostly for 16-bit images

offset

offset value

Adds the constant value (specified in ADU) to the current image. This constant can take a negative value.

In 16-bit mode, values of pixels that fall outside of [0, 65535] are clipped. In 32-bit mode, no clipping occurs

parse

328 Chapter 19. Commands

 Siril, Release 1.2.0

parse str [-r]

Parses the string str using the information contained in the header of the image currently loaded. Main purpose of
this command is to debug path parsing of header keys which can be used in other commands.
Option -r specifies the string is to be interpreted in read mode. In read mode, all wilcards defined in string str are
used to find a file name matching the pattern. Otherwise, default mode is write mode and wildcards, if any, are
removed from the string to be parsed.

If str starts with $def prefix, it will be recognized as a reserved keyword and looked for in the strings stored in
gui_prepro.dark_lib, gui_prepro.flat_lib, gui_prepro.bias_lib or gui_prepro.stack_default for $defdark, $defflat,
$defbias or $defstack respectively.
The keyword $seqname$ can also be used when a sequence is loaded

pcc

pcc [image_center_coords] [-noflip] [-platesolve] [-focal=] [-pixelsize=] [-limitmag=[+-

˓→]] [-catalog=] [-downscale]

Run the Photometric Color Correction on the loaded image.

If the image has already been plate solved, the PCC can reuse the astrometric solution, otherwise, or if WCS or other
image metadata is erroneous or missing, arguments for the plate solving must be passed:
the approximate image center coordinates can be provided in decimal degrees or degree/hour minute second values
(J2000 with colon separators), with right ascension and declination values separated by a comma or a space.
focal length and pixel size can be passed with -focal= (in mm) and -pixelsize= (in microns), overriding values from
image and settings.
you can force the plate solving to be remade using the -platesolve flag.

Unless -noflip is specified and the image is detected as being upside-down, the image will be flipped if a plate solving
is run.
For faster star detection in big images, downsampling the image is possible with -downscale.

The limit magnitude of stars used for plate solving and PCC is automatically computed from the size of the field of
view, but can be altered by passing a +offset or -offset value to -limitmag=, or simply an absolute positive value for
the limit magnitude.
The star catalog used is NOMAD by default, it can be changed by providing -catalog=apass. If installed locally, the
remote NOMAD (the complete version) can be forced by providing -catalog=nomad

Links: nomad

329
Siril, Release 1.2.0

platesolve

platesolve [image_center_coords] [-noflip] [-platesolve] [-focal=] [-pixelsize=] [-

˓→limitmag=[+-]] [-catalog=] [-localasnet] [-downscale]

Plate solve the loaded image.

If the image has already been plate solved nothing will be done, unless the -platesolve argument is passed to force a
new solve. If WCS or other image metadata is erroneous or missing, arguments must be passed:
the approximate image center coordinates can be provided in decimal degrees or degree/hour minute second values
(J2000 with colon separators), with right ascension and declination values separated by a comma or a space (not
mandatory for astrometry.net).
focal length and pixel size can be passed with -focal= (in mm) and -pixelsize= (in microns), overriding values from
image and settings.

Unless -noflip is specified, if the image is detected as being upside-down, it will be flipped.
For faster star detection in big images, downsampling the image is possible with -downscale.

Images can be either plate solved by Siril using a star catalog and the global registration algorithm or by
astrometry.net's local solve-field command (enabled with -localasnet).
The following options apply to Siril's plate solve only.
The limit magnitude of stars used for plate solving is automatically computed from the size of the field of view, but
can be altered by passing a +offset or -offset value to -limitmag=, or simply an absolute positive value for the limit
magnitude.
The choice of the star catalog is automatic unless the -catalog= option is passed: if local catalogs are installed, they
are used, otherwise the choice is based on the field of view and limit magnitude. If the option is passed, it forces the
use of the remote catalog given in argument, with possible values: tycho2, nomad, gaia, ppmxl, brightstars, apass

pm

pm "expression" [-rescale [low] [high]]

This command evaluates the expression given in argument as in PixelMath tool. The full expression must be between
double quotes and variables (that are image names, without extension, located in the working directory in that case)
must be surrounded by the token $, e.g. "$image1$ * 0.5 + $image2$ * 0.5". A maximum of 10 images can be used in
the expression.
Image can be rescaled with the option -rescale followed by low and high values in the range [0, 1]. If no low and high
values are provided, default values are set to 0 and 1

preprocess

330 Chapter 19. Commands

 Siril, Release 1.2.0

preprocess sequencename [-bias=filename] [-dark=filename] [-flat=filename] [-cc=dark␣

˓→[siglo sighi] || -cc=bpm bpmfile] [-cfa] [-debayer] [-fix_xtrans] [-equalize_cfa] [-

˓→opt] [-all] [-prefix=] [-fitseq]

Calibrates the sequence sequencename using bias, dark and flat given in argument.

For bias, a uniform level can be specified instead of an image, by entering a quoted expression starting with an = sign,
such as -bias="=256" or -bias="=64*$OFFSET".

By default, cosmetic correction is not activated. If you wish to apply some, you will need to specify it with -cc=
option.
You can use -cc=dark to detect hot and cold pixels from the masterdark (a masterdark must be given with the -dark=
option), optionally followed by siglo and sighi for cold and hot pixels respectively. A value of 0 deactivates the
correction. If sigmas are not provided, only hot pixels detection with a sigma of 3 will be applied.
Alternatively, you can use -cc=bpm followed by the path to your Bad Pixel Map to specify which pixels must be
corrected. An example file can be obtained with a find_hot command on a masterdark.

Three options apply to color images (in CFA format): -cfa for cosmetic correction purposes, -debayer to demosaic
images before saving them, and -equalize_cfa to equalize the mean intensity of RGB layers of the master flat, to avoid
tinting the calibrated image.
The -fix_xtrans option is dedicated to X-Trans images by applying a correction on darks and biases to remove a
rectangle pattern caused by autofocus.
It is also possible to optimize the dark subtraction with -opt, which requires both bias and dark masters to be provided.
By default, frames marked as excluded will not be processed. The argument -all can be used to force processing of all
frames even if marked as excluded.
The output sequence name starts with the prefix "pp_" unless otherwise specified with option -prefix=.
If -fitseq is provided, the output sequence will be a FITS sequence (single file)

This command is now deprecated: CALIBRATE should be used instead.

Links: calibrate

preprocess_single

preprocess_single imagename [-bias=filename] [-dark=filename] [-flat=filename] [-cfa] [-

˓→debayer] [-fix_xtrans] [-equalize_cfa] [-opt] [-prefix=]

Calibrates the image imagename using bias, dark and flat given in argument.

For bias, a uniform level can be specified instead of an image, by entering a quoted expression starting with an = sign,
such as -bias="=256" or -bias="=64*$OFFSET".

331
Siril, Release 1.2.0

By default, cosmetic correction is not activated. If you wish to apply some, you will need to specify it with -cc=
option.
You can use -cc=dark to detect hot and cold pixels from the masterdark (a masterdark must be given with the -dark=
option), optionally followed by siglo and sighi for cold and hot pixels respectively. A value of 0 deactivates the
correction. If sigmas are not provided, only hot pixels detection with a sigma of 3 will be applied.
Alternatively, you can use -cc=bpm followed by the path to your Bad Pixel Map to specify which pixels must be
corrected. An example file can be obtained with a find_hot command on a masterdark.

Three options apply to color images (in CFA format): -cfa for cosmetic correction purposes, -debayer to demosaic
images before saving them, and -equalize_cfa to equalize the mean intensity of RGB layers of the master flat, to avoid
tinting the calibrated image.
The -fix_xtrans option is dedicated to X-Trans images by applying a correction on darks and biases to remove a
rectangle pattern caused by autofocus.
It is also possible to optimize the dark subtraction with -opt, which requires both bias and dark masters to be provided.
The output filename starts with the prefix "pp_" unless otherwise specified with option -prefix=

This command is now deprecated: CALIBRATE_SINGLE should be used instead.

Links: calibrate_single

psf

psf [channel]

Performs a PSF (Point Spread Function) on the selected star and display the results. For headless operation, the
selection can be given in pixels using BOXSELECT. If provided, the channel argument selects the image channel on
which the star will be analyzed. It can be omitted for monochrome images or when run from the GUI with one of the
channels active in the view

Links: boxselect

register

register sequencename [-2pass] [-noout] [-drizzle] [-prefix=] [-minpairs=] [-transf=] [-

˓→layer=] [-maxstars=] [-nostarlist] [-interp=] [-noclamp] [-selected]

Finds and optionally performs geometric transforms on images of the sequence given in argument so that they may be
superimposed on the reference image. Using stars for registration, this algorithm only works with deep sky images.

332 Chapter 19. Commands

 Siril, Release 1.2.0

Star detection options can be changed using SETFINDSTAR or the Dynamic PSF dialog. The detection is done on
the green layer for colour images, unless specified by the -layer= option with an argument ranging from 0 to 2 for red
to blue.

The -2pass and -noout options will only compute the transforms but not generate the transformed images, -2pass
adds a preliminary pass to the algorithm to find a good reference image before computing the transforms, based on
image quality and framing. To generate transformed images after this pass, use SEQAPPLYREG. -nostarlist disables
saving the star lists to disk.

The option -transf= specifies the use of either shift, similarity, affine or homography (default) transformations
respectively.
The option -drizzle activates the sub-pixel stacking by up-scaling by 2 the generated images.
The option -minpairs= will specify the minimum number of star pairs a frame must have with the reference frame,
otherwise the frame will be dropped and excluded from the sequence.
The option -maxstars= will specify the maximum number of star to find within each frame (must be between 100 and
2000). With more stars, a more accurate registration can be computed, but will take more time to run.

The pixel interpolation method can be specified with the -interp= argument followed by one of the methods in the list
no[ne], ne[arest], cu[bic], la[nczos4], li[near], ar[ea]}. If none is passed, the transformation is forced to shift and a
pixel-wise shift is applied to each image without any interpolation.
Clamping of the bicubic and lanczos4 interpolation methods is the default, to avoid artefacts, but can be disabled with
the -noclamp argument.

All images of the sequence will be registered unless the option -selected is passed, in that case the excluded images
will not be processed

If created, the output sequence name starts with the prefix "r_" unless otherwise specified with -prefix= option

Links: setfindstar, psf , seqapplyreg

reloadscripts

reloadscripts

Rescans the scripts folders and updates the Scripts menu

requires

requires version

333
Siril, Release 1.2.0

Returns an error if the version of Siril is older than the one passed in argument

resample

resample { factor | -width= | -height= } [-interp=] [-noclamp]

Resamples the loaded image, either with a factor factor or for the target width or height provided by either of
-width= or -height=. This is generally used to resize images, a factor of 0.5 divides size by 2.
In the graphical user interface, we can see that several interpolation algorithms are proposed.

The pixel interpolation method can be specified with the -interp= argument followed by one of the methods in the list
no[ne], ne[arest], cu[bic], la[nczos4], li[near], ar[ea]}. If none is passed, the transformation is forced to shift and a
pixel-wise shift is applied to each image without any interpolation.
Clamping of the bicubic and lanczos4 interpolation methods is the default, to avoid artefacts, but can be disabled with
the -noclamp argument

rgbcomp

rgbcomp red green blue [-out=result_filename]

rgbcomp -lum=image { rgb_image | red green blue } [-out=result_filename]

Creates an RGB composition using three independent images, or an LRGB composition using the optional luminance
image and three monochrome images or a color image. Result image is called composed_rgb.fit or composed_lrgb.fit
unless another name is provided in the optional argument

rgradient

rgradient xc yc dR dalpha

Creates two images, with a radial shift (dR in pixels) and a rotational shift (dalpha in degrees) with respect to the
point (xc, yc).

Between these two images, the shifts have the same amplitude, but an opposite sign. The two images are then added
to create the final image. This process is also called Larson Sekanina filter

334 Chapter 19. Commands

 Siril, Release 1.2.0

rl

rl [-loadpsf=] [-alpha=] [-iters=] [-stop=] [-gdstep=] [-tv] [-fh] [-mul]

Restores an image using the Richardson-Lucy method.

Optionally, a PSF may be loaded using the argument -loadpsf=filename (created with MAKEPSF).

The number of iterations is provide by -iters (the default is 10).

The type of regularization can be set with -tv for Total Variation, or -fh for the Frobenius norm of the Hessian matrix
(the default is none) and -alpha= provides the regularization strength (lower value = more regularization, default =
3000).

By default the gradient descent method is used with a default step size of 0.0005, however the multiplicative method
may be specified with -mul.

The stopping criterion may be activated by specifying a stopping limit with -stop=

Links: psf , makepsf

rmgreen

rmgreen [-nopreserve] [type] [amount]

Applies a chromatic noise reduction filter. It removes green tint in the current image. This filter is based on
PixInsight's SCNR and it is also the same filter used by HLVG plugin in Photoshop.
Lightness is preserved by default but this can be disabled with the -nopreserve switch.

Type can take values 0 for average neutral, 1 for maximum neutral, 2 for maximum mask, 3 for additive mask,
defaulting to 0. The last two can take an amount argument, a value between 0 and 1, defaulting to 1

rotate

rotate degree [-nocrop] [-interp=] [-noclamp]

335
Siril, Release 1.2.0

Rotates the loaded image by an angle of degree value. The option -nocrop can be added to avoid cropping to the
image size (black borders will be added).

Note: if a selection is active, i.e. by using a command `boxselect` before `rotate`, the resulting image will be a rotated
crop. In this particular case, the option -nocrop will be ignored if passed.

The pixel interpolation method can be specified with the -interp= argument followed by one of the methods in the list
no[ne], ne[arest], cu[bic], la[nczos4], li[near], ar[ea]}. If none is passed, the transformation is forced to shift and a
pixel-wise shift is applied to each image without any interpolation.
Clamping of the bicubic and lanczos4 interpolation methods is the default, to avoid artefacts, but can be disabled with
the -noclamp argument

rotatePi

rotatePi

Rotates the loaded image of an angle of 180° around its center. This is equivalent to the command "ROTATE 180" or
"ROTATE -180"

Links: rotate

satu

satu amount [background_factor [hue_range_index]]

Enhances the color saturation of the loaded image. Try iteratively to obtain best results.
amount can be a positive number to increase color saturation, negative to decrease it, 0 would do nothing, 1 would
increase it by 100%
background_factor is a factor to (median + sigma) used to set a threshold for which only pixels above it would be
modified. This allows background noise to not be color saturated, if chosen carefully. Defaults to 1. Setting 0 disables
the threshold.
hue_range_index can be [0, 6], meaning: 0 for pink to orange, 1 for orange to yellow, 2 for yellow to cyan, 3 for
cyan, 4 for cyan to magenta, 5 for magenta to pink, 6 for all (default)

save

336 Chapter 19. Commands

 Siril, Release 1.2.0

save filename

Saves current image to filename.fit (or .fits, depending on your preferences, see SETEXT) in the current working
directory. The image remains loaded. filename can contain a path as long as the directory already exists

Links: setext

savebmp

savebmp filename

Saves current image under the form of a bitmap file with 8-bit per channel: filename.bmp (BMP 24-bit)

savejpg

savejpg filename [quality]

Saves current image into a JPG file: filename.jpg.

The compression quality can be adjusted using the optional quality value, 100 being the best and default, while a
lower value increases the compression ratio

savepng

savepng filename

Saves current image into a PNG file: filename.png, with 16 bits per channel if the loaded image is 16 or 32 bits, and 8
bits per channel if the loaded image is 8 bits

savepnm

337
Siril, Release 1.2.0

savepnm filename

Saves current image under the form of a NetPBM file format with 16-bit per channel.

The extension of the output will be filename.ppm for RGB image and filename.pgm for gray-level image

savetif

savetif filename [-astro] [-deflate]

Saves current image under the form of a uncompressed TIFF file with 16-bit per channel: filename.tif. The option
-astro allows saving in Astro-TIFF format, while -deflate enables compression.

See also SAVETIF32 and SAVETIF8

savetif32

savetif32 filename [-astro] [-deflate]

Same command as SAVETIF but the output file is saved in 32-bit per channel: filename.tif. The option -astro allows
saving in Astro-TIFF format, while -deflate enables compression

Links: savetif

savetif8

savetif8 filename [-astro] [-deflate]

Same command as SAVETIF but the output file is saved in 8-bit per channel: filename.tif. The option -astro allows
saving in Astro-TIFF format, while -deflate enables compression

Links: savetif

338 Chapter 19. Commands

 Siril, Release 1.2.0

sb

sb [-loadpsf=] [-alpha=] [-iters=]

Restores an image using the Split Bregman method.

Optionally, a PSF may be loaded using the argument -loadpsf=filename.

The number of iterations is provide by -iters (the default is 1).

The regularization factor -alpha= provides the regularization strength (lower value = more regularization, default =
3000)

Links: psf

select

select sequencename from to

This command allows easy mass selection of images in the sequence sequencename (from from to to included).
This is a selection for later processing.
See also UNSELECT

Links: unselect

seqapplyreg

seqapplyreg sequencename [-drizzle] [-interp=] [-noclamp] [-layer=] [-framing=] [-

˓→prefix=] [-filter-fwhm=value[%|k]] [-filter-wfwhm=value[%|k]] [-filter-round=value[

˓→%|k]] [-filter-bkg=value[%|k]] [-filter-nbstars=value[%|k]] [-filter-quality=value[

˓→%|k]] [-filter-incl[uded]]

Applies geometric transforms on images of the sequence given in argument so that they may be superimposed on the
reference image, using registration data previously computed (see REGISTER).

The output sequence name starts with the prefix "r_" unless otherwise specified with -prefix= option.

339
Siril, Release 1.2.0

The option -drizzle activates up-scaling by 2 the images created in the transformed sequence.

The pixel interpolation method can be specified with the -interp= argument followed by one of the methods in the list
no[ne], ne[arest], cu[bic], la[nczos4], li[near], ar[ea]}. If none is passed, the transformation is forced to shift and a
pixel-wise shift is applied to each image without any interpolation.
Clamping of the bicubic and lanczos4 interpolation methods is the default, to avoid artefacts, but can be disabled with
the -noclamp argument.

The registration is done on the first layer for which data exists for RGB images unless specified by -layer= option (0, 1
or 2 for R, G and B respectively).

Automatic framing of the output sequence can be specified using -framing= keyword followed by one of the methods
in the list { current | min | max | cog } :
-framing=max (bounding box) adds a black border around each image as required so that no part of the image is
cropped when registered.
-framing=min (common area) crops each image to the area it has in common with all images of the sequence.
-framing=cog determines the best framing position as the center of gravity (cog) of all the images.

Filtering out images:

Images to be registered can be selected based on some filters, like those selected or with best FWHM, with some of
the -filter-* options.

Links: register

With filtering being some of these in no particular order or number:

[-filter-fwhm=value[%|k]] [-filter-wfwhm=value[%|k]] [-filter-round=value[%|k]] [-filter-

˓→bkg=value[%|k]]

[-filter-nbstars=value[%|k]] [-filter-quality=value[%|k]] [-filter-incl[uded]]

Best images from the sequence can be stacked by using the filtering arguments. Each of these arguments can remove
bad images based on a property their name contains, taken from the registration data, with either of the three types of
argument values:
- a numeric value for the worse image to keep depending on the type of data used (between 0 and 1 for roundness and
quality, absolute values otherwise),
- a percentage of best images to keep if the number is followed by a % sign,
- or a k value for the k.sigma of the worse image to keep if the number is followed by a k sign.
It is also possible to use manually selected images, either previously from the GUI or with the select or unselect
commands, using the -filter-included argument.

340 Chapter 19. Commands

 Siril, Release 1.2.0

seqclean

seqclean sequencename [-reg] [-stat] [-sel]

This command clears selection, registration and/or statistics data stored for the sequence sequencename.

You can specify to clear only registration, statistics and/or selection with -reg, -stat and -sel options respectively. All
are cleared if no option is passed

seqcosme

seqcosme sequencename [filename].lst [-prefix=]

Same command as COSME but for the the sequence sequencename. Only selected images in the sequence are
processed.

The output sequence name starts with the prefix "cosme_" unless otherwise specified with option -prefix=

Links: cosme

seqcosme_cfa

seqcosme_cfa sequencename [filename].lst [-prefix=]

Same command as COSME_CFA but for the the sequence sequencename. Only selected images in the sequence are
processed.

The output sequence name starts with the prefix "cosme_" unless otherwise specified with option -prefix=

Links: cosme_cfa

seqcrop

seqcrop sequencename x y width height [-prefix=]

341
Siril, Release 1.2.0

Crops the sequence given in argument sequencename. Only selected images in the sequence are processed.

The crop selection is specified by the upper left corner position x and y and the selection width and height, like for
CROP.
The output sequence name starts with the prefix "cropped_" unless otherwise specified with -prefix= option

Links: crop

seqextract_Green

seqextract_Green sequencename [-prefix=]

Same command as EXTRACT_GREEN but for the sequence sequencename.

The output sequence name starts with the prefix "Green_" unless otherwise specified with option -prefix=

seqextract_Ha

seqextract_Ha sequencename [-prefix=]

Same command as EXTRACT_HA but for the sequence sequencename.

The output sequence name starts with the prefix "Ha_" unless otherwise specified with option -prefix=

seqextract_HaOIII

seqextract_HaOIII sequencename [-resample=]

Same command as EXTRACT_HAOIII but for the sequence sequencename.

The output sequences names start with the prefixes "Ha_" and "OIII_"

342 Chapter 19. Commands

 Siril, Release 1.2.0

seqfind_cosme

seqfind_cosme sequencename cold_sigma hot_sigma [-prefix=]

Same command as FIND_COSME but for the sequence sequencename.

The output sequence name starts with the prefix "cc_" unless otherwise specified with -prefix= option

Links: find_cosme

seqfind_cosme_cfa

seqfind_cosme_cfa sequencename cold_sigma hot_sigma [-prefix=]

Same command as FIND_COSME_CFA but for the sequence sequencename.

The output sequence name starts with the prefix "cc_" unless otherwise specified with -prefix= option

Links: find_cosme_cfa

seqfindstar

seqfindstar sequencename [-layer=] [-maxstars=]

Same command as FINDSTAR but for the sequence sequencename.

The option -out= is not available for this process as all the star list files are saved with the default name
seqname_seqnb.lst

Links: findstar

seqfixbanding

seqfixbanding sequencename amount sigma [-prefix=] [-vertical]

343
Siril, Release 1.2.0

Same command as FIXBANDING but for the sequence sequencename.

The output sequence name starts with the prefix "unband_" unless otherwise specified with -prefix= option

Links: fixbanding

seqght

seqght sequence -D= [-B=] [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat]␣
˓→[channels] [-prefix=]

Same command as GHT but the sequence must be specified as the first argument. In addition, the optional argument
-prefix= can be used to set a custom prefix

Links: ght

seqheader

seqheader sequencename keyword [-out=file.csv]

Prints the FITS header value for the given key for all images in the sequence

seqinvght

seqinvght sequence -D= [-B=] [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat]␣
˓→[channels] [-prefix=]

Same command as INVGHT but the sequence must be specified as the first argument. In addition, the optional
argument -prefix= can be used to set a custom prefix

Links: invght

344 Chapter 19. Commands

 Siril, Release 1.2.0

seqinvmodasinh

seqinvmodasinh sequence -D= [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat]␣
˓→[channels] [-prefix=]

Same command as INVMODASINH but the sequence must be specified as the first argument. In addition, the
optional argument -prefix= can be used to set a custom prefix

Links: invmodasinh

seqlinstretch

seqlinstretch sequence -BP= [channels] [-sat] [-prefix=]

Same command as LINSTRETCH but the sequence must be specified as the first argument. In addition, the optional
argument -prefix= can be used to set a custom prefix

Links: linstretch

seqmerge_cfa

seqmerge_cfa sequencename bayerpattern [-prefixin=] [-prefixout=]

Same command as MERGE_CFA but for the sequence sequencename.

The Bayer pattern to be reconstructed must be provided as the second argment as one of RGGB, BGGR, GBRG or
GRBG.

The input filenames contain the identifying prefix "CFA_" and a number unless otherwise specified with -prefixin=
option.

Note: all 4 sets of input files must be present and must be consistently named, the only difference being the number
after the identifying prefix.

The output sequence name starts with the prefix "mCFA_" and a number unless otherwise specified with -prefixout=
option

Links: merge_cfa

345
Siril, Release 1.2.0

seqmodasinh

seqmodasinh sequence -D= [-LP=] [-SP=] [-HP=] [-human | -even | -independent | -sat]␣
˓→[channels] [-prefix=]

Same command as MODASINH but the sequence must be specified as the first argument. In addition, the optional
argument -prefix= can be used to set a custom prefix

Links: modasinh

seqmtf

seqmtf sequencename low mid high [channels] [-prefix=]

Same command as MTF but for the sequence sequencename.

The output sequence name starts with the prefix "mtf_" unless otherwise specified with -prefix= option

Links: mtf

seqpsf

seqpsf [sequencename channel { -at=x,y | -wcs=ra,dec }]

Same command as PSF but runs on sequences. This is similar to the one-star registration, except results can be used
for photometry analysis rather than aligning images and the coordinates of the star can be provided by options.
This command is what is called internally by the menu that appears on right click in the image, with the PSF for the
sequence entry. By default, it will run with parallelisation activated; if registration data already exists for the sequence,
they will be used to shift the search window in each image. If there is no registration data and if there is significant
shift between images in the sequence, the default settings will fail to find stars in the initial position of the search area.
The follow star option can then be activated by going in the registration tab, selecting the one-star registration and
checking the follow star movement box (default in headless if no registration data is available).

Results will be displayed in the Plot tab, from which they can also be exported to a comma-separated values (CSV)
file for external analysis.

346 Chapter 19. Commands

 Siril, Release 1.2.0

When creating a light curve, the first star for which seqpsf has been run, marked 'V' in the display, will be considered
as the variable star. All others are averaged to create a reference light curve subtracted to the light curve of the
variable star.

Currently, in headless operation, the command prints some analysed data in the console, another command allows
several stars to be analysed and plotted as a light curve: LIGHT_CURVE. Arguments are mandatory in headless, with
-at= allowing coordinates in pixels to be provided for the target star and -wcs= allowing J2000 equatorial coordinates
to be provided.

Links: psf , light_curve

seqplatesolve

seqplatesolve sequencename [image_center_coords] [-noflip] [-platesolve] [-focal=] [-

˓→pixelsize=] [-limitmag=[+-]] [-catalog=] [-localasnet] [-downscale]

Plate solve a sequence. A new sequence will be created with the prefix "ps_".
If images have already been plate solved, they will just be copied, unless the -platesolve argument is passed to force a
new solve. If WCS or other image metadata are erroneous or missing, arguments must be passed:
the approximate image center coordinates can be provided in decimal degrees or degree/hour minute second values
(J2000 with colon separators), with right ascension and declination values separated by a comma or a space (not
mandatory for astrometry.net). A single catalog extract will be done for the entire sequence, if there is a lot of drift
that may not succeed for all images.
focal length and pixel size can be passed with -focal= (in mm) and -pixelsize= (in microns), overriding values from
images and settings.

Unless -noflip is specified, if images are detected as being upside-down, they will be flipped.
For faster star detection in big images, downsampling the image is possible with -downscale.

Images can be either plate solved by Siril using a star catalog and the global registration algorithm or by
astrometry.net's local solve-field command (enabled with -localasnet).
The following options apply to Siril's plate solve only.
The limit magnitude of stars used for plate solving is automatically computed from the size of the field of view, but
can be altered by passing a +offset or -offset value to -limitmag=, or simply an absolute positive value for the limit
magnitude.
The choice of the star catalog is automatic unless the -catalog= option is passed: if local catalogs are installed, they
are used, otherwise the choice is based on the field of view and limit magnitude. If the option is passed, it forces the
use of the remote catalog given in argument, with possible values: tycho2, nomad, gaia, ppmxl, brightstars, apass

seqrl

347
Siril, Release 1.2.0

seqrl sequencename [-loadpsf=] [-alpha=] [-iters=] [-stop=] [-gdstep=] [-tv] [-fh] [-mul]

The same as the RL command, but applies to a sequence which must be specified as the first argument

Links: rl

seqsb

sb sequencename [-loadpsf=] [-alpha=] [-iters=]

The same as the SB command, but applies to a sequence which must be specified as the first argument

Links: sb

seqsplit_cfa

seqsplit_cfa sequencename [-prefix=]

Same command as SPLIT_CFA but for the sequence sequencename.

The output sequences names start with the prefix "CFA_" and a number unless otherwise specified with -prefix=
option.
Limitation: the sequence always outputs a sequence of FITS files, no matter the type of input sequence

Links: split_cfa

seqstarnet

seqstarnet sequencename [-stretch] [-upscale] [-stride=value] [-nostarmask]

This command calls Starnet++ to remove stars from the sequence sequencename. See STARNET

Links: starnet

348 Chapter 19. Commands

 Siril, Release 1.2.0

seqstat

seqstat sequencename output_file [option] [-cfa]

Same command as STAT for sequence sequencename.

Data is saved as a csv file output_file.

The optional parameter defines the number of statistical values computed: basic, main (default) or full (more
detailed but longer to compute).
\tbasic includes mean, median, sigma, bgnoise, min and max
\tmain includes basic with the addition of avgDev, MAD and the square root of BWMV
\tfull includes main with the addition of location and scale.

If -cfa is passed and the images are CFA, statistics are made on per-filter extractions

Links: stat

seqsubsky

seqsubsky sequencename { -rbf | degree } [-nodither] [-samples=20] [-tolerance=1.0] [-

˓→smooth=0.5] [-prefix=]

Same command as SUBSKY but for the sequence sequencename.

Dithering, required for low dynamic gradients, can be disabled with -nodither.

The output sequence name starts with the prefix "bkg_" unless otherwise specified with -prefix= option. Only
selected images in the sequence are processed

Links: subsky

seqtilt

seqtilt sequencename

Same command as TILT but for the sequence sequencename. It generally gives better results

349
Siril, Release 1.2.0

Links: tilt

sequnsetmag

sequnsetmag

Resets the magnitude calibration and reference star for the sequence. See SEQSETMAG

Links: seqsetmag

seqwiener

wiener sequencename [-loadpsf=] [-alpha=]

The same as the WIENER command, but applies to a sequence which must be specified as the first argument

Links: wiener

set

set { -import=inifilepath | variable=value }

Updates a setting value, using its variable name, with the given value, or a set of values using an existing ini file with
-import= option.
See GET to get values or the list of variables

Links: get

set16bits

set16bits

350 Chapter 19. Commands

 Siril, Release 1.2.0

Forbids images to be saved with 32 bits per channel on processing, use 16 bits instead

set32bits

set32bits

Allows images to be saved with 32 bits per channel on processing

setcompress

setcompress 0/1 [-type=] [q]

Defines if images are compressed or not.

0 means no compression while 1 enables compression.

If compression is enabled, the type must be explicitly written in the option -type= ("rice", "gzip1", "gzip2").
Associated to the compression, the quantization value must be within [0, 256] range.

For example, "setcompress 1 -type=rice 16" sets the rice compression with a quantization of 16

setcpu

setcpu number

Defines the number of processing threads used for calculation.

Can be as high as the number of virtual threads existing on the system, which is the number of CPU cores or twice
this number if hyperthreading (Intel HT) is available. The default value is the maximum number of threads available,
so this should mostly be used to limit processing power. This is reset on every Siril run. See also SETMEM

Links: setmem

351
Siril, Release 1.2.0

setext

setext extension

Sets the extension used and recognized by sequences.

The argument extension can be "fit", "fts" or "fits"

setfindstar

setfindstar [reset] [-radius=] [-sigma=] [-roundness=] [-focal=] [-pixelsize=] [-

˓→convergence=] [ [-gaussian] | [-moffat] ] [-minbeta=] [-relax=on|off] [-minA=] [-

˓→maxA=] [-maxR=]

Defines stars detection parameters for FINDSTAR and REGISTER commands.

Passing no parameter lists the current values.

Passing reset resets all values to defaults. You can then still pass values after this keyword.

Configurable values:

-radius= defines the radius of the initial search box and must be between 3 and 50.
-sigma= defines the threshold above noise and must be greater than or equal to 0.05.
-roundness= defines minimum star roundness and must between 0 and 0.95. -maxR allows an upper bound to
roundness to be set, to visualize only the areas where stars are significantly elongated, do not change for registration.
-minA and -maxA define limits for the minimum and maximum amplitude of stars to keep, normalized between 0
and 1.
-focal= defines the focal length of the telescope.
-pixelsize= defines the pixel size of the sensor.
-gaussian and -moffat configure the solver model to be used (Gaussian is the default).
If Moffat is selected, -minbeta= defines the minimum value of beta for which candidate stars will be accepted and
must be greater than or equal to 0.0 and less than 10.0.
-convergence= defines the number of iterations performed to fit PSF and should be set between 1 and 3 (more
tolerant).
-relax= relaxes the checks that are done on star candidates to assess if they are stars or not, to allow objects not
shaped like stars to still be accepted (off by default)

Links: findstar, register, psf

352 Chapter 19. Commands

 Siril, Release 1.2.0

setmag

setmag magnitude

Calibrates the magnitudes by selecting a star and giving the known apparent magnitude.

All PSF computations will return the calibrated apparent magnitude afterwards, instead of an apparent magnitude
relative to ADU values. Note that the provided value must match the magnitude for the observation filter to be
meaningful.
To reset the magnitude constant see UNSETMAG

Links: psf , unsetmag

seqsetmag

seqsetmag magnitude

Same as SETMAG command but for the loaded sequence.

This command is only valid after having run SEQPSF or its graphical counterpart (select the area around a star and
launch the PSF analysis for the sequence, it will appear in the graphs).
This command has the same goal as SETMAG but recomputes the reference magnitude for each image of the
sequence where the reference star has been found.
When running the command, the last star that has been analysed will be considered as the reference star. Displaying
the magnitude plot before typing the command makes it easy to understand.
To reset the reference star and magnitude offset, see SEQUNSETMAG

Links: setmag, seqpsf , psf , sequnsetmag

setmem

setmem ratio

Sets a new ratio of used memory on free memory.

Ratio value should be between 0.05 and 2, depending on other activities of the machine. A higher ratio should allow
siril to process faster, but setting the ratio of used memory above 1 will require the use of on-disk memory, which is
very slow and unrecommended, even sometimes not supported, leading to system crash. A fixed amount of memory
can also be set in the generic settings, with SET, instead of a ratio

353
Siril, Release 1.2.0

Links: set

setphot

setphot [-inner=20] [-outer=30] [-aperture=10] [-force_radius=no] [-gain=2.3] [-min_

˓→val=0] [-max_val=60000]

Gets or sets photometry settings, mostly used by SEQPSF. If arguments are provided, they will update the settings.
None are mandatory, any can be provided, default values are shown in the command's syntax. At the end of the
command, the active configuration will be printed. Aperture is dynamic unless forced, the aperture value from
settings is not used if dynamic, FWHM is used instead. Gain is used only if not available from the FITS header

Links: seqpsf

setref

setref sequencename image_number

Sets the reference image of the sequence given in first argument. image_number is the sequential number of the
image in the sequence, not the number in the filename, starting at 1

show

show [-clear] [{ -list=file.csv | [name] RA Dec }]

Shows a point on the loaded plate solved image using the temporary user annotations catalog, based on its equatorial
coordinates. The -clear option clears this catalog first and can be used alone. Several points can be passed using a
CSV file with the option -file= containing a name (cannot start with a digit), RA and Dec. This is only available from
the GUI of Siril

solsys

354 Chapter 19. Commands

 Siril, Release 1.2.0

solsys [-mag=20.0]

Searches and displays Solar System objects in the current loaded and plate solved image's field of view, using the
online IMCCE SkyBoT cone search tool. Use -mag= to change the limit magnitude, defaults to 20

split

split file1 file2 file3 [-hsl | -hsv | -lab]

Splits the loaded color image into three distinct files (one for each color) and saves them in file1.fit, file2.fit and
file3.fit files. A last argument can optionally be supplied, -hsl, -hsv or lab to perform an HSL, HSV or CieLAB
extraction. If no option are provided, the extraction is of RGB type, meaning no conversion is done

split_cfa

split_cfa

Splits the loaded CFA image into four distinct files (one for each channel) and saves them in files

stack

stack seqfilename
stack seqfilename { sum | min | max } [filtering] [-output_norm] [-out=filename]
stack seqfilename { med | median } [-nonorm, -norm=] [filtering] [-fastnorm] [-rgb_
˓→equal] [-output_norm] [-out=filename]

stack seqfilename { rej | mean } [rejection type] [sigma_low sigma_high] [-rejmap[s]] [-

˓→nonorm, -norm=] [filtering] [-fastnorm] [ -weight_from_noise | -weight_from_nbstack | -

˓→weight_from_wfwhm | -weight_from_nbstars ] [-rgb_equal] [-output_norm] [-out=filename]

Stacks the sequencename sequence, using options.

Rejection type:
The allowed types are: sum, max, min, med (or median) and rej (or mean). If no argument other than the sequence
name is provided, sum stacking is assumed.

355
Siril, Release 1.2.0

Stacking with rejection:

Types rej or mean require the use of additional arguments for rejection type and values. The rejection type is one of
n[one], p[ercentile], s[igma], m[edian], w[insorized], l[inear], g[eneralized], [m]a[d] for Percentile, Sigma,
Median, Winsorized, Linear-Fit, Generalized Extreme Studentized Deviate Test or k-MAD clipping. If omitted, the
default Winsorized is used.
The sigma low and sigma high parameters of rejection are mandatory unless none is selected.
Optionally, rejection maps can be created, showing where pixels were rejected in one (-rejmap) or two (-rejmaps, for
low and high rejections) newly created images.

Normalization of input images:

For med (or median) and rej (or mean) stacking types, different types of normalization are allowed: -norm=add for
additive, -norm=mul for multiplicative. Options -norm=addscale and -norm=mulscale apply same normalization
but with scale operations. -nonorm is the option to disable normalization. Otherwise addtive with scale method is
applied by default.
-fastnorm option specifies to use faster estimators for location and scale than the default IKSS.
-rgb_equal will use normalization to equalize color image backgrounds, useful if PCC and unlinked
AUTOSTRETCH will not be used.

Other options for rejection stacking:

-weight_from_noise is an option to add larger weights to frames with lower background noise.
-weight_from_nbstack weights input images based on how many images were used to create them, useful for live
stacking.
-weight_from_nbstars or -weight_from_wfwhm weight input images based on number of stars or wFWHM
computed during registration step.

Outputs:
Result image name can be set with the -out= option. Otherwise, it will be named as sequencename_stacked.fit.
-output_norm applies a normalization to rescale result in the [0, 1] range (median and mean stacking only).

Filtering out images:

Images to be stacked can be selected based on some filters, like manual selection or best FWHM, with some of the
-filter-* options.

Links: pcc, autostretch

With filtering being some of these in no particular order or number:

[-filter-fwhm=value[%|k]] [-filter-wfwhm=value[%|k]] [-filter-round=value[%|k]] [-filter-

˓→bkg=value[%|k]]

[-filter-nbstars=value[%|k]] [-filter-quality=value[%|k]] [-filter-incl[uded]]

Best images from the sequence can be stacked by using the filtering arguments. Each of these arguments can remove
bad images based on a property their name contains, taken from the registration data, with either of the three types of

356 Chapter 19. Commands

 Siril, Release 1.2.0

argument values:
- a numeric value for the worse image to keep depending on the type of data used (between 0 and 1 for roundness and
quality, absolute values otherwise),
- a percentage of best images to keep if the number is followed by a % sign,
- or a k value for the k.sigma of the worse image to keep if the number is followed by a k sign.
It is also possible to use manually selected images, either previously from the GUI or with the select or unselect
commands, using the -filter-included argument.

stackall

stackall
stackall { sum | min | max } [filtering]
stackall { med | median } [-nonorm, norm=] [-filter-incl[uded]]
stackall { rej | mean } [rejection type] [sigma_low sigma_high] [-nonorm, norm=]␣
˓→[filtering] [ -weight_from_noise | -weight_from_wfwhm | -weight_from_nbstars | -weight_

˓→from_nbstack ] [-rgb_equal] [-out=filename]

Opens all sequences in the current directory and stacks them with the optionally specified stacking type and filtering
or with sum stacking. See STACK command for options description

Links: stack

starnet

starnet [-stretch] [-upscale] [-stride=value] [-nostarmask]

Calls StarNet to remove stars from the loaded image.

Prerequisite: StarNet is an external program, with no affiliation with Siril, and must be installed correctly prior the
first use of this command, with the path to its CLI version installation correctly set in Preferences / Miscellaneous.

The starless image is loaded on completion, and a star mask image is created in the working directory unless the
optional parameter -nostarmask is provided.

Optionally, parameters may be passed to the command:

- The option -stretch is for use with linear images and will apply a pre-stretch before running StarNet and the inverse
stretch to the generated starless and starmask images.
- To improve star removal on images with very tight stars, the parameter -upscale may be provided. This will
upsample the image by a factor of 2 prior to StarNet processing and rescale it to the original size afterwards, at the
expense of more processing time.

357
Siril, Release 1.2.0

- The optional parameter -stride=value may be provided, however the author of StarNet strongly recommends that the
default stride of 256 be used

start_ls

start_ls [-dark=filename] [-flat=filename] [-rotate] [-32bits]

Initializes a livestacking session, using the optional calibration files and waits for input files to be provided by the
LIVESTACK command until STOP_LS is called. Default processing will use shift-only registration and 16-bit
processing because it's faster, it can be changed to rotation with -rotate and -32bits

Note that the live stacking commands put Siril in a state in which it's not able to process other commands. After
START_LS, only LIVESTACK, STOP_LS and EXIT can be called until STOP_LS is called to return Siril in its normal,
non-live-stacking, state

Links: livestack, stop_ls, exit

stat

stat [-cfa] [main]

Returns statistics of the current image, the basic list by default or the main list if main is passed. If a selection is
made, statistics are computed within the selection. If -cfa is passed and the image is CFA, statistics are made on
per-filter extractions

stop_ls

stop_ls

Stops the live stacking session. Only possible after START_LS

Links: start_ls

358 Chapter 19. Commands

 Siril, Release 1.2.0

subsky

subsky { -rbf | degree } [-dither] [-samples=20] [-tolerance=1.0] [-smooth=0.5]

Computes a synthetic background gradient using either the polynomial function model of degree degrees or the RBF
model (if -rbf is provided instead) and subtracts it from the image.
The number of samples per horizontal line and the tolerance to exclude brighter areas can be adjusted with the
optional arguments. Tolerance is in MAD units: median + tolerance * mad.
Dithering, required for low dynamic gradients, can be enabled with -dither.
For RBF, the additional smoothing parameter is also available

synthstar

synthstar

Fixes imperfect stars from the loaded image. No matter how much coma, tracking drift or other distortion your stars
have, if Siril's star finder routine can detect it, synthstar will fix it. To use intensive care, you may wish to manually
detect all the stars you wish to fix. This can be done using the findstar console command or the Dynamic PSF dialog.
If you have not run star detection, it will be run automatically with default settings.

For best results synthstar should be run before stretching.

The output of synthstar is a fully corrected synthetic star mask comprising perfectly round star PSFs (Moffat or
Gaussian profiles depending on star saturation) computed to match the intensity, FWHM, hue and saturation
measured for each star detected in the input image. This can then be recombined with the starless image to produce an
image with perfect stars.

No parameters are required for this command

Links: psf

threshlo

threshlo level

Replaces values below level in the loaded image with level

359
Siril, Release 1.2.0

threshhi

threshi level

Replaces values above level in the loaded image with level

thresh

thresh lo hi

Replaces values below level in the loaded image with level

tilt

tilt [clear]

Computes the sensor tilt as the FWHM difference between the best and worst corner truncated mean values. The
clear option allows to clear the drawing

unclipstars

unclipstars

Re-profiles clipped stars of the loaded image to desaturate them, scaling the output so that all pixel values are <= 1.0

unselect

unselect sequencename from to

Allows easy mass unselection of images in the sequence sequencename (from from to to included). See SELECT

360 Chapter 19. Commands

 Siril, Release 1.2.0

Links: select

unsetmag

unsetmag

Resets the magnitude calibration to 0. See SETMAG

Links: setmag

unsharp

unsharp sigma multi

Applies an unsharp mask, actually a Gaussian filtered image with sigma sigma and a blend with the parameter
amount used as such: out = in * (1 + amount) + filtered * (-amount).

See also GAUSS, the same without blending

Links: gauss

visu

visu low high

Displays the loaded image with low and high as the low and high threshold, GUI only

wavelet

wavelet nbr_layers type

361
Siril, Release 1.2.0

Computes the wavelet transform of the loaded image on (nbr_layers=1...6) layer(s) using linear (type=1) or bspline
(type=2) version of the 'à trous' algorithm. The result is stored in a file as a structure containing the layers, ready for
weighted reconstruction with WRECONS.

See also EXTRACT

Links: wrecons, extract

wiener

wiener [-loadpsf=] [-alpha=]

Restores an image using the Wiener deconvolution method.

Optionally, a PSF created by MAKEPSF may be loaded using the argument -loadpsf=filename.

The parameter -alpha= provides the Gaussian noise modelled regularization factor

Links: psf , makepsf

wrecons

wrecons c1 c2 c3 ...

Reconstructs to current image from the layers previously computed with wavelets and weighted with coefficients c1,
c2, ..., cn according to the number of layers used for wavelet transform, after the use of WAVELET

Links: wavelet

362 Chapter 19. Commands

 CHAPTER

TWENTY

HOW TO REPORT ISSUES

If, despite studying the documentation and tutorials, you're experiencing strange behavior, this page is here to tell you
what to do in such a situation. First of all, if you think there's a problem, just saying it doesn't work won't help us
finding a solution. We're not soothsayers and need information to identify the problem and devise a solution. So it's
important that you tell us what you were doing at the time the problem occurred, what operating system you're using,
what version of Siril you're using and most importantly logs!

20.1 Check changelogs and bug trackers

First of all, if you find a bug in Siril, it may already have been reported (sometimes literally dozens of times). We
therefore ask you to check first, for example by looking at changelogs, or tickets that have already been opened, and
even closed.

20.2 Send us useful information

As mentioned in the introduction, we need useful information to help solve the problem:
1. What operating system you're using? Because Siril can behave very differently on Windows, Linux or macOS,
we need to know this information. Please be as precise as possible.
2. Which version of Siril do you use? And how did you get it? Package downlaoded on the website? Through a
third party? Compiled by yourself? Here again, please, be as precise as possible.
3. Sometimes it's useful to share screenshots. However, please DO NOT TAKE YOUR SCREENSHOTS WITH
YOUR SMARTPHONE - it's illegible. Your operating system is capable of making screenshots very easily
(Google can help you with this) and Siril also offers such a feature (the button with the camera). Finally, the
desired formats are image formats: jpg, bmp or png, but absolutely not pdf.
4. Send us logs. Ideally, we prefer English logs! Just go to Siril preferences and change the language to English in
the User Interface tab. Also, There are two types of logs: the one displayed in the Siril console, which describes
the steps performed by the software and can help us debug, and the internal logs that are visible when Siril is run
from the command line:
• The former are very useful in most cases, and can be exported very easily using the button at the bottom
right of them. This creates a file that can easily be sent to us.
• However, when the software crashes (i.e. suddenly closes without warning), you need to start Siril from
the command line, trying to reproduce the crash and retrieve the logs. Here, the method depends on the
operating system.
– Microsoft Windows: Open a cmd window (type cmd in Windows Search bar) and type the following:

363
Siril, Release 1.2.0

"C:\Program Files\Siril\bin\siril.exe" 2>&1 >output.log

This will save the file output.log to the folder where the terminal was started (in most cases in
%USERPROFILE% folder).
– macOS: If you've installed Siril in the Applications folder, as is generally recommended, then start by
opening the Terminal application from the Utilities folder within Applications, then copy and paste the
following line:

/Applications/Siril.app/Contents/MacOS/siril > ~/Desktop/output.log 2>&1

After the crash, the logs will be available on the desktop in the file output.log.
– GNU/Linux: Simply start Siril in a terminal. Usually, the binary is located in the $PATH variable, in
which case type:

siril > output.log 2>&1

is all you need to get the logs redirected in the file output.log. This will save the file output.log to
the folder where the terminal was started
5. Send us your pic. If you find your image strange, don't hesitate to share it with us, usually in FITS format. It's
always more interesting than a screenshot. To do this, you need to use a large file exchange service. There are
lots of them, and we can suggest WeTransfer, for example. In that case, upload your data to WeTransfer and get
a download link to share.

20.3 How to contact us?

There are several ways to contact us and report a bug. The easiest is to find us on the forum. But it is also possible to
open a ticket on our gitlab repository. In this case, please check first that the same ticket has not already been opened.
It may even have been closed because it has been resolved, in which case, a short description with a ticket number will
be shown in the Changelog. To visualize the ticket (even a closed one) and confirm you are, or not, experiencing the
same issue, go to the address https://gitlab.com/free-astro/siril/-/issues/XXXX with XXXX the ticket number.

364 Chapter 20. How to report issues

 BIBLIOGRAPHY

[Fischler1981] Fischler, M. A., & Bolles, R. C. (1981). Random sample consensus: a paradigm for model fitting with
applications to image analysis and automated cartography. Communications of the ACM, 24(6), 381-395.
[Valdes1995] Valdes, F. G., Campusano, L. E., Velasquez, J. D., & Stetson, P. B. (1995). FOCAS automatic catalog
matching algorithms. Publications of the Astronomical Society of the Pacific, 107(717), 1119.
[Peter2009] Peter J. Huber and E. Ronchetti (2009), Robust Statistics, 2nd Ed., Wiley
[ConejeroPI] Juan Conejero, ImageIntegration, Pixinsight Tutorial
[Rosner1983] Rosner, B. (1983). Percentage points for a generalized ESD many-outlier procedure. Technometrics,
25(2), 165-172.
[Anger2018] Anger, J., Facciolo, G., & Delbracio, M. (2018). Estimating an image's blur kernel using natural image
statistics, and deblurring it: an analysis of the Goldstein-Fattal method. Image Processing On Line, 8,
282-304. https://doi.org/10.5201/ipol.2018.211
[Anger2019] Anger, J., Facciolo, G., & Delbracio, M. (2019). Blind image deblurring using the l0 gradient prior.
Image processing on line, 9, 124-142. https://doi.org/10.5201/ipol.2019.243
[Goldstein2012] Goldstein, A., & Fattal, R. (2012, October). Blur-kernel estimation from spectral irregularities. In
European Conference on Computer Vision (pp. 622-635). Springer, Berlin, Heidelberg. https://doi.org/10.
1007/978-3-642-33715-4_45
[Lucy1974] Lucy, L. B. (1974). An iterative technique for the rectification of observed distributions. The astronomical
journal, 79, 745. https://doi.org/10.1086/111605.
[Lebrun2013] Lebrun, M., Buades, A., & Morel, J. M. (2013) Implementation of the “Non-Local Bayes” (NL-Bayes)
Image Denoising Algorithm. Image Processing On Line, 3 , pp. 1–42. https://doi.org/10.5201/ipol.2013.16
[Pierazzo2017] Pierazzo, N., & Facciolo, G. (2017). Data adaptive dual domain denoising: a method to boost state of
the art denoising algorithms. Image Processing On Line, 7, 93-114. https://doi.org/10.5201/ipol.2017.203
[Mäkitalo2011] Mäkitalo, M., & Foi, A. (2012, March). Poisson-gaussian denoising using the exact unbiased inverse
of the generalized anscombe transformation. In 2012 IEEE International Conference on Acoustics, Speech
and Signal Processing (ICASSP) (pp. 1081-1084). IEEE. https://doi.org/10.1109/ICASSP.2012.6288074
[Mäkitalo2012] Makitalo, M., & Foi, A. (2011). A closed-form approximation of the exact unbiased inverse of the
Anscombe variance-stabilizing transformation. IEEE transactions on image processing, 20(9), 2697-2698.
https://doi.org/10.1109/TIP.2011.2121085
[Romano2015] Romano, Y., & Elad, M. (2015). Boosting of image denoising algorithms. SIAM Journal on Imaging
Sciences, 8(2), 1187-1219. https://doi.org/10.1137/140990978
[Wright2003] Wright, Grady Barrett. Radial basis function interpolation: numerical and analytical developments.
University of Colorado at Boulder, 2003.

365
Siril, Release 1.2.0

[Stetson1987] Stetson, P. B. (1987). DAOPHOT: A computer program for crowded-field stellar photometry. Publica-
tions of the Astronomical Society of the Pacific, 99(613), 191.

366 Bibliography
 INDEX

A extract_HaOIII, 313
addmax, 303
asinh, 303 F
autoghs, 304 fdiv, 313
autostretch, 304 ffill, 314
fftd, 314
B ffti, 314
bg, 304 fill, 314
bgnoise, 304 find_cosme, 315
binxy, 305 find_cosme_cfa, 315
boxselect, 305 find_hot, 315
findstar, 316
C fix_xtrans, 316
fixbanding, 316
calibrate, 305
fmedian, 317
calibrate_single, 306
fmul, 317
capabilities, 306
catsearch, 307
cd, 307
G
cdg, 307 gauss, 317
clahe, 308 get, 317
clear, 308 getref, 318
clearstar, 308 ght, 318
close, 308 grey_flat, 318
convert, 308
convertraw, 309 H
cosme, 309 help, 319
cosme_cfa, 309 histo, 319
crop, 310
I
D iadd, 319
ddp, 310 idiv, 319
denoise, 310 imul, 320
dir, 311 inspector, 320
dumpheader, 312 invght, 320
invmodasinh, 320
E invmtf, 321
entropy, 312 isub, 321
exit, 312
extract, 312 J
extract_Green, 313 jsonmetadata, 321
extract_Ha, 313

367
Siril, Release 1.2.0

L savebmp, 337
light_curve, 322 savejpg, 337
linear_match, 322 savepng, 337
link, 322 savepnm, 337
linstretch, 323 savetif, 338
livestack, 323 savetif32, 338
load, 323 savetif8, 338
log, 324 sb, 339
ls, 324 select, 339
seqapplyreg, 339
M seqclean, 340
seqcosme, 341
makepsf, 324
seqcosme_cfa, 341
merge, 325
seqcrop, 341
merge_cfa, 325
seqextract_Green, 342
mirrorx, 326
seqextract_Ha, 342
mirrorx_single, 326
seqextract_HaOIII, 342
mirrory, 326
seqfind_cosme, 343
modasinh, 326
seqfind_cosme_cfa, 343
mtf, 327
seqfindstar, 343
N seqfixbanding, 343
seqght, 344
neg, 327 seqheader, 344
new, 327 seqinvght, 344
nomad, 328 seqinvmodasinh, 345
nozero, 328 seqlinstretch, 345
seqmerge_cfa, 345
O seqmodasinh, 346
offset, 328 seqmtf, 346
seqplatesolve, 347
P seqpsf, 346
parse, 328 seqrl, 347
pcc, 329 seqsb, 348
platesolve, 329 seqsetmag, 353
pm, 330 seqsplit_cfa, 348
preprocess, 330 seqstarnet, 348
preprocess_single, 331 seqstat, 349
psf, 332 seqsubsky, 349
seqtilt, 349
R sequnsetmag, 350
register, 332 seqwiener, 350
reloadscripts, 333 set, 350
requires, 333 set16bits, 350
resample, 334 set32bits, 351
rgbcomp, 334 setcompress, 351
rgradient, 334 setcpu, 351
rl, 335 setext, 352
rmgreen, 335 setfindstar, 352
rotate, 335 setmag, 352
rotatePi, 336 setmem, 353
setphot, 354
S setref, 354
satu, 336 show, 354
save, 336 solsys, 354

368 Index
 Siril, Release 1.2.0

split, 355
split_cfa, 355
stack, 355
stackall, 357
starnet, 357
start_ls, 358
stat, 358
stop_ls, 358
subsky, 359
synthstar, 359

T
thresh, 360
threshhi, 360
threshlo, 359
tilt, 360

U
unclipstars, 360
unselect, 360
unsetmag, 361
unsharp, 361

V
visu, 361

W
wavelet, 361
wiener, 362
wrecons, 362

Index 369