Welcome to Siril's documentation!

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.

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 designed 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.).

Minimum System Requirements

To ensure optimal performance, it is recommended that your system meets the following minimum specifications:

• RAM: At least 8GB of RAM is recommended for all systems to ensure smooth operation. Higher RAM capacity is beneficial as Siril utilizes available RAM extensively for processing tasks.

• Storage: An SSD (Solid State Drive) is highly recommended for faster read/write speeds, resulting in order-of-magnitude faster execution compared to traditional HDDs

Specific platform requirements are as follows:

• Windows: Windows 8.1 or later.

• macOS: macOS 10.15 Catalina or later.

• GNU/Linux: No specific minimum requirements stated. Typically, any modern distribution should suffice.

Installation on GNU/Linux

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:

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

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.

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

Installation on Microsoft Windows

Installation with the installer

The recommended way to install Siril is to use the provided installer which will guide you step by step.

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

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

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.

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.)

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.

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.

Building on Windows with Msys2

These instructions are made for compiling on Windows with MSYS2 distribution using MinGW. MSYS2 requires 64 bit Windows 8.1 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

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
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

Installation on macOS

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.

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.

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.

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

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.

• 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.

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 depending on the case.

Table below lists all configurable options.

Option	Type	Value	Choices	Description
relocatable-bundle	combo	platform-default	[ 'yes', 'no', 'platform-default' ]	build with resources considered bundled under the same prefix
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-default	[ 'yes', 'no', 'platform-default' ]	Use libcurl instead of GIO
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.

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

• 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

Installation on Arch Linux

Two packages are available on AUR: siril and siril-git. Download the PKGBUILD or the repository, install dependencies, 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

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 installed 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.

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.

Main interface

When launching Siril, the main interface opens.

Note

Click anywhere onto the image below to display its functions.

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 working directory

Back to figure

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.

  

  Save dialog box.

  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

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

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.

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

Burger Menu

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.

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.

Dynamic PSF

Opens the Dynamic PSF dialog.

Shortcuts

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

Image information window

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).

Working Directory

The Working Directory (wd), also known as the Current Working Directory (cwd), is the directory in which Siril works. Its choice is a crucial step, especially when using scripts. The wrong choice of cwd is responsible for 90% of script failures. This folder is selected by clicking on the Home button, in the shape of a house: . This is the directory where Siril saves images by default (if no other path is specified) and also the directory where it searches for sequences.

Once the directory has been selected, its path can be easily checked in the title bar of the application window, below the version in use as illustrated in the figure below.

Working Directory path shown in the title bar. Here, this is a Linux path.

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.

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.

FITS/SER debayer

Page 1 of preferences dialog

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 automatically 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 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 preferences. 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.

FITS Options

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
  

  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

Astrometry

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.

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 \(m_{ij}\) (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 \(i = j\) 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 \(s_i m_{ij}\). 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.

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.

• 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 %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 here.

• Show solve-field output: print the output of the solver in Siril's main log window, otherwise, only the outcome will be given.

Pre-processing

Page 4 of preferences dialog

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 possible to use any value given in the FITS header as a keyword and surround it with $ tokens. If the keyword 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.

• 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

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.

Photometry

Page 5 of preferences dialog

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.

Circle of the aperture photometry

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.

• 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.

Analysis Tools

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.

Aberration inspector window

User Interface

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.

• 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 preference. 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

Scripts

Page 8 of preferences dialog

• 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 application 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.

Performances

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. 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 performance 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.

Miscellaneous

Page 10 of preferences dialog

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.

• 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 metadata.

• 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.

Preferences (commands)

Starting from v1.2, most preferences can also be set through commands, meaning either from direct input in the command 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 ([Range])	Type	Comment
core.wd	(not set)	directory	current working directory
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, 1e+06]	double	amount of memory in GB
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	directory	swap directory
core.binning_update	true	boolean	update pixel size of binned images
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
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.fftwf_strategy	0	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 algorithm
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 [-65536, 65534]	double	minimum valid pixel value for photometry
photometry.maxval	60000 [1, 65535]	double	maximum valid pixel value for photometry
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
astrometry.asnet_max_seconds_run	10 [0, 100000]	integer	maximum seconds to try solving
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
astrometry.percent_scale_range	20 [0, 50]	integer	percent below and above the expected sampling to allow
analysis.panel	256 [127, 1024]	integer	panel size of aberration inspector
analysis.window	381 [300, 1600]	integer	window size of aberration inspector
compression.enabled	false	boolean	FITS compression enabled
compression.method	0 [0, 3]	integer	FITS compression method
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	$seqname$stacked	string	default stack name
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 interpolation
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
gui.icon_symbolic	false	boolean	icon style
gui.script_path		list of strings	list of script directories
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.mmb_zoom_action	0	integer	Middle mouse button double click zoom action
gui.color_bkg_samples	rgba(255, 51, 26, 1.0)	string	configure background samples color
gui.color_std_annotations	rgba(128, 255, 77, 0.9)	string	configure standard annotation color
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 strings	list of pixel math presets

(*). 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:

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

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.

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.

Linear image saved in 16-bit

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

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.

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.

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.

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.

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.

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.

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.

FITS

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.

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 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.

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).

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.

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)

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.

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.

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
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

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.

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.

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,
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

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.

Save Dialog with Astro-TIFF option

Siril command line

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

Sample files

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

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

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.

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

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.

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 endianness 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.

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.

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.

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.

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.

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.

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.

Loading a sequence

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.

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.

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

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 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.

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.

Sequence export

Give a name and specify output format to export a sequence.

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.

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.

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.

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

Definitions and workflow

Astrophotography is the process of capturing images of celestial objects. It involves several steps, including preprocessing 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 astrophotographer 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.

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.

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.

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.

Source panel of the conversion tab.

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.

Destination panel of the conversion tab.

Thus, for a sequence name basename, the converted files will be of the form

basenameXXXXX.[ext]

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.

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

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.

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

Calibration

Once a sequence is loaded, images can be calibrated, registered and stacked. The calibration is an optional, yet important, 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.

Master files

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.

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.

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 = 2^{11}\).

Fore more details, please refer to the tutorial on the Synthetic biases.

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.

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

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

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.

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.

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

The solution is therefore to subtract the bias to the dark, then integrate the bias subtraction with those of the images, 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\)).

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

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

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.

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.

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 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.

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.

X-Trans artifact fixed by the algorithm of Siril

Cosmetic Correction

Cosmetic correction is the technique used to correct defective pixels in images. Indeed, any camera sensor has photosites 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 \(\sigma\). 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. The last line has been added by hand and corrects a damaged column located at position \(x = 1527\).

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

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.

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.

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=

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 expressions:

\[\begin{split}\begin{align} L &= a - b \times \left(x-\frac{W}{2}\right)^2 + d_\text{rate} \times t_{\text{lights}} +o \\ D &= d_\text{rate} \times t_{\text{lights}} + o \\ F &= K\left(a - b \times \left(x-\frac{W}{2}\right)^2\right) + o \\ O &= o \end{align}\end{split}\]

with, \(L\) for Lights, \(D\) for Darks, \(F\) for Flats and \(O\) for Bias.

For the lights \(L\), the first part is a spatial illumination component, i.e., \(a - b(x-\frac{W}{2})^2\). We have chosen here a quadratic variation with a maximum value \(a\) in the middle of the frame of width \(W\), 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 (\(d_\text{rate} \times t_\text{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 \(D\) 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 \(F\) also have a spatial term, proportional to the term found in the lights. The factor \(K\), 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 \(O\) 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.

• \(a = 200 \text{[ADU]}\)

• \(b = 0.0003 \text{[ADU/px}^2\text{]}\)

• \(d_\text{rate} = 1 \text{[ADU/s]}\)

• \(t_{\text{lights}} = 10 \text{[s]}\)

• \(o = 2048 \text{[ADU]}\)

• \(W = 1000 \text{[px]}\)

\(L\), \(D\) and \(O\) values in ADU are given on the left scale while \(F\) 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:

\[L_c = \dfrac{L -D}{F-O}.\]

The term \(F-O\) 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 \(L-D\) 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:

\[L_c = \dfrac{1}{K}.\]

No spatial variation term is left, you have flat-fielded your lights! Getting a sensible value in ADU (and not \(1/K\)) is what Siril does when you check Auto evaluate normalisation value in the Calibration tab.

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:

• \(L-D\) : you have just shot darks.

• \(L/F\) : you have just shot flats.

• \(L/(F-O)\) : you have shot flats and corrected them by an offset (either a master or a synthetic one).

• \((L-O)/(F-O)\) : you have just flats corrected by offset. But you have subtracted the offset from your lights as well.

• \((L-D)/F\) : you have shot flats and darks but no offsets.

• \((L-D)/(F-O)\) : you have done everything by the book.

Interestingly, you can notice that:

• \(L-D\) shows obviously no correction for vignetting.

• Both \(L/F\) and \(L/(F-O)\) show overcorrection or inverse vignetting.

• Getting very close to the optimal result, \((L-D)/F\) and \((L-O)/(F-O)\) 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:

• 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 \((L-D)/(F-O)\) 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.

\(L-D\)

\(L/F\)

\(L/(F-O)\)

\((L-O)/(F-O)\)

\((L-D)/(F-O)\)

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.

  

  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.

• 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 consequence 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.

  

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

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).

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.

Algorithms

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

Registration method	Feature detection	Transformation calculation	Shift	Euclidean	Similarity	Affine	Homography
Global	Dynamic PSF	Triangles matching + RANSAC	subpixel		x	x	x
2 pass			subpixel		x	x	x
1-2-3 stars	PSF minimization in selection box	Singular Value Decomposition (2-3 stars) Difference (1 star)	subpixel (1 star)	(2-3 stars)
Image Pattern alignment	cross correlation on selection box		pixel
KOMBAT	Max of convolution in spatial domain on selection box		pixel
Comet	PSF minimization in selection box	Shifts from velocity vector using timestamps	subpixel
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 homography, 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 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:

  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

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.

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 elaborate star detection algorithm that avoids as much as possible to select objects that are not stars in the fastest possible 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.

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 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.

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

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.

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 \(\Delta x\) and \(\Delta y\) 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.

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.

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

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

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).

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:

[-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.

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.

• 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 resulting 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.

References

[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.

Stacking

The final preprocessing step to do with Siril is to stack the images. Image stacking is a technique used in astrophotography 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.

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 \(\sqrt{N}\), where \(N\) 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.

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 \(\sqrt{N}\). 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(\(\sigma\) low, \(\sigma\) 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 (\(y=ax+b\)) 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.

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.

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\sqrt{N}\) and is therefore worse than stacking by average which is generally preferred.

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.

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 normalisation.

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 multiplication 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.

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

Note

The bias and dark masters should not be processed with normalisation. However, multiplicative normalisation 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.

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-\(\sigma\) to either retain a given percentage of images or to calculate the allowable threshold using k-\(\sigma\) 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).

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.

References

[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.

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.

Image processing menu

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.

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.

Dialog box of Asinh Transformation

For monochrome images, pixel values are modified using the following function:

\[\text{pixel} = \frac{(\text{original} - \text{blackpoint})\times\text{asinh}(\text{original}\times\text{stretch})}{\text{original}\times\text{asinh}(\text{stretch})}\]

For color images, the function becomes:

\[\text{pixel} = \frac{(\text{original} - \text{blackpoint})\times\text{asinh}(\text{rgb}\_\text{original}\times\text{stretch})}{\text{rgb}\_\text{original}\times\text{asinh}(\text{stretch})}\]

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

Theory

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 avoid this problem the RGB blend clipping algorithm is used. This was devised by the same authors as the Generalised Hyperbolic Stretch transforms. The \((r, g, b)\) values are stretched first based on the luminance value rgb_original to give \((r', g', b')\). Then the original \((r, g, b)\) values are independently stretched to give \((r'', g'', b'')\). Finally the largest value of \(k\) is identified such that

\(k \times r' + ( 1 - k ) \times r'' ≤ 1\);

\(k \times g' + ( 1 - k ) \times g'' ≤ 1\);

and

\(k \times b' + ( 1 - k ) \times b'' ≤ 1\)

Then the transformed values are calculated as

\(( k \times r' + ( 1 - k ) \times r'', k \times g' + ( 1 - k ) \times g'', k \times b' + ( 1 - k ) \times b'')\)

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 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

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.

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 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.

Theory

The new pixel values are then computed with this function:

(1)\[\begin{split}\text{MTF}(x_p) = \frac{(m - 1)x_p}{(2m - 1)x_p - m}. \\\end{split}\]

• For \(x_p=0\), \(\text{MTF} = 0\),

• for \(x_p=m\), \(\text{MTF} = 0.5\),

• for \(x_p=1\), \(\text{MTF} = 1\),

where \(x_p\) is the pixel value defined as follow

(2)\[x_p=\frac{\text{original}-\text{shadows}}{\text{highlights}-\text{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

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

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.

Dialog box of the Generalized Hyperbolic Stretch

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.

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:

The Generalized Hyperbolic Stretch with a color image

• 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 transform stretch with SP set to around 0.5, and HP brought down low enough to flatten the upper end of the saturation histogram.

  

  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.

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 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

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

Colors

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:

Manual Color Calibration dialog 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 astrometry. And now, the tool is also available as the pcc command, so it can be embedded in image post-processing scripts.

Photometric Color Calibration dialog window.

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

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

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.

Color Saturation dialog window.

Siril command line

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)

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.

Remove Green Noise dialog window.

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 \(a\) 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 Undo and Redo buttons in order to fine-tune the value.

Protection method

Maximum Mask Protection

\[\begin{split}m &= \text{max}(R,B) \\ G'&= G\times (1 — a)\times (1 — m) + m\times G\end{split}\]

Additive Mask Protection

\[\begin{split}m &= \text{min}(1,R+B) \\ G'&= G\times (1 — a)\times (1 — m) + m\times G\end{split}\]

Average Neutral Protection (default method)

\[\begin{split}m &= 0.5\times (R + B) \\ G'&= \text{min}(G, m)\end{split}\]

Maximum Neutral Protection

\[\begin{split}m &= \text{max}(R,B) \\ G'&= \text{min}(G, m)\end{split}\]

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]

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

Negative Transform

Negative transformation refers to subtracting pixel values from \((L−1)\), where \(L\) 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.

Original image with weak signal (Image Cyril Richard).

Negative image where the signal is more visible (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.

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

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.

À Trous Wavelets Transform

A wavelet is a function at the base of the wavelet decomposition, a decomposition similar to the short term Fourier transform, 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.

An example of four different types of wavelets.

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.

Wavelet tool dialog box.

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.

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.

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 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

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.

Original image with visible banding.

Banding Reduction dialog box.

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.

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

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]

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

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.

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

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.

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

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.

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 \(m_{5\times 5}\) the median of the 5 nearest neighbors. If the pixel value is greater than

\[m_{5\times 5}+\text{max}(\text{avgDev}, \sigma_\text{high}\times \text{avgDev}),\]

with avgDev, the Average Deviation of the whole image.

Then the pixel is replaced by the average of the \(3\times 3\) pixels: \(a_{3\times 3}\), but only if

\[a_{3\times 3} < m_{5\times 5}+\frac{\text{avgDev}}{2}.\]

Cold pixels detection

If the pixel value is less than

\[m_{5\times 5} - (\sigma_\text{low}\times \text{avgDev}),\]

then the pixel is replaced by \(m_{5\times 5}\).

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

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.

Example of deconvolution on star field.

Deconvolution is accessed through the Image Processing menu or using Siril commands.

Dialog box of the deconvolution tool.

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

• \(\boldsymbol{ℓ_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 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 Gaussian 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 regularization. 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 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 (\(\lambda\)). Regularization parameter for PSF estimation. Try decreasing this value for noisy images.

\(\boldsymbol{ℓ_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.

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 converging 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.

    

    An example of Moffat PSF with fwhm=5", Angle=45°, Ratio=1.20, \(\beta=4.5\) and a PSF size of 15.

  • Disk PSFs are used to deconvolve images that are out of focus.

    

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

  • Airy disc PSFs are used to deconvolve the diffraction that arises as a physical consequence of diffraction by the aperture of your telescope.

    

    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.

• FWHM specifies the full width at half maximum of the chosen profile (for disc PSFs it simply specifies the radius).

• Beta (\(\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 available, 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 implementation.

• 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 around stars. For deconvolving stretched images, however, this can be unnecessarily slow, so using the multiplicative 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 library. 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.

Rogues' Gallery

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

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

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.)

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.

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.

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.

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 \(\boldsymbol{ℓ_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.

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.

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 \(\boldsymbol{\alpha}\) at the default, and deconvolving the image using a blind estimated \(\boldsymbol{ℓ_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.

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.

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 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.

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

[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.

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.

Direct Transform tab.

To reconstruct the image, click on the Inverse Transform tab and enter the filepath of the modulus and phase images.

Inverse Transform tab.

Siril command line

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

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

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.

Median dialog window.

The layout of the window dialog is quite simple and few settings are available.

• Kernel size: From \(3\times 3\) to \(15\times 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

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

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 \(n\) images increases the correlated signal by a factor of \(n\) whereas the uncorrelated noise only increases by a factor of \(\sqrt{n}\). 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 development 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 representative of the real live data.

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]

  • 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 \(k+1\) is given by \(x_{k+1}=f(y+x_k)-x_k\) where \(y\) 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 removing, and then an inverse transform is applied on completion. The transform chosen for use in Siril is the Anscombe transform \(A: x\rightarrow 2\times \sqrt{\left(x+\frac{3}{8}\right)}\)

  • As the transform is non-linear, use of the direct algebraic inverse results would bias the output. Siril therefore uses a closed-form approximation to the exact unbiased inverse, which is quick to calculate and produces 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!)

Denoising a photon-starved image

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 images: 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.

Siril Noise Reduction GUI

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

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

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

Noisy image

Denoised with NL-Bayes only

Denoised with NL-Bayes only

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

Use of modulation

Denoised with NL-Bayes using the Anscombe transform

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

Denoised with DA3D using a NL-Bayes guide image

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

Denoised with NL-Bayes and SOS

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

Limitations

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

• 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

[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

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.

Dialog box of the Rotational Gradient filter.

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 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.

Image of a comet whose tail is barely visible.

A simple click on Apply will apply the filter. In our example, the tail becomes visible.

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

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

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.

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.

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.

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.

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

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 images 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.

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.

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.

Using Star Recomposition combine a starless image and star mask of the Alnitak region

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.

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.

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
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.

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.

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

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

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 resynthesized 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.

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

Geometry

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.

Rotate&Crop dialog box showing all settings.

Five interpolation algorithms are available:

• 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 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.

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

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).

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

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

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).

Binning dialog box

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

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.

Resample dialog box

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

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.

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

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:

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 \(\phi(\mathbf{x}) = \phi(\| \mathbf{x} \|)\), whereby in our case we use the Euclidean norm \(\| \mathbf{x} \| = \sqrt{x_1^2 + x_2^2}\). The function \(f\), which describes the background model, can now be expressed as a linear combination

\[f(\mathbf{x}) = \sum_i w_i \, \phi(\|\mathbf{x} - \mathbf{x_i}\|) + o\]

where \(w_i\) corresponds to the weights for the different sample points and \(o\) corresponds to a constant offset.

The requirement that the function \(f\) should pass through the sample points results in the condition

\[\begin{split}\begin{pmatrix} \phi(\mathbf{x}_1 - \mathbf{x}_1) & \phi(\mathbf{x}_1 - \mathbf{x}_2) & \dots & \phi(\mathbf{x}_1 - \mathbf{x}_N) & 1 \\ \phi(\mathbf{x}_2 - \mathbf{x}_1) & \phi(\mathbf{x}_2 - \mathbf{x}_2) & \dots & \phi(\mathbf{x}_2 - \mathbf{x}_N) & 1 \\ \vdots & \vdots & \ddots & \vdots \\ \phi(\mathbf{x}_N - \mathbf{x}_1) & \phi(\mathbf{x}_N - \mathbf{x}_2) & \dots & \phi(\mathbf{x}_N - \mathbf{x}_N) & 1 \\ 1 & 1 & \dots & 1 & 0 \end{pmatrix} \begin{pmatrix} w_1 \\ w_2 \\ \vdots \\ w_N \\ o \end{pmatrix} = \begin{pmatrix} y_1 \\ y_2 \\ \vdots \\ y_N \\ 0 \end{pmatrix} \, ,\end{split}\]

which can only be fulfilled if the matrix on the left-hand side is invertible. With the right choice of function \(\phi\) this can always be guaranteed [Wright2003].

In addition, the summand \(s \, I\) is added to the matrix on the left-hand side, where \(s\) is a smoothing parameter and \(I\) is the unit matrix. The summand causes a regularization, which results in a smoother result the larger the parameter \(s\) 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 \(\phi(|\mathbf{x}|) = |\mathbf{x}|^2 \log(|\mathbf{x}|)\).

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

\[\begin{equation} f(x)=a_nx^n+a_{n-1}x^{n-1}+\cdots+a_2x^2+a_1x+a_0 \end{equation}.\]

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

General settings

• Add dither: Hit this option when color banding is produced after background extraction. Dither is an intentionally 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.

  • Division: it is mainly used to correct multiplicative phenomena, such as vignetting or differential atmospheric 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

[Wright2003]

Wright, Grady Barrett. Radial basis function interpolation: numerical and analytical developments. University of Colorado at Boulder, 2003.

Extraction

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.

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

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.

  

  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.

  \[ \begin{align}\begin{aligned}\text{G}_\text{i} = \text{G}_\text{io} \times \frac{3 \times \overline{\text{G}_\text{o}}}{2 \times \overline{\text{G}_\text{o}} + \overline{\text{B}_\text{o}}}\\\text{B}_\text{i} = \text{B}_\text{io} \times \frac{3 \times \overline{\text{B}_\text{o}}}{2 \times \overline{\text{G}_\text{o}} + \overline{\text{B}_\text{o}}}\end{aligned}\end{align} \]

  Where \(\text{B}_\text{i}\) is the \(i^{\text{th}}\) blue pixel, \(\text{B}_\text{io}\) is the \(i^{\text{th}}\) original blue pixel and \(\overline{\text{B}_\text{o}}\) 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.

  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.

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.

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.

Wavelet Layers extraction dialog box.

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.

Original image of M45 (courtesy of V. Cohas).

6 extracted planes.

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.

Linear match dialog

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

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:

• 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

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_).

  • 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 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

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.

Pixel Math dialog box as shown at opening

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.

   

   Pixel Math parameters box

4. The output field is reserved for scaling the image within a given range. One need to expand the frame before using it.

   

   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.

   

   Pixel Math presets

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.

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.

Original image.

The following expression:

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

will produce a star mask.

After the formula above.

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

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).

Pixel oriented functions

Function	Use case	Definition
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 \(x > 0\) \(−1\) if \(x < 0\) \(\;0\) if \(x = 0\).
sin	sin ( x )	Sine of x.
sinh	sinh ( x )	Hyperbolic sine of x.
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.

Statistics functions

Function	Use case	Definition
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.

Operators

Operators

Operator	Use case	Definition
~	~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.

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.

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.

Plot tab as shown after a global registration.

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.

• Roundness: The roundness r is computed as the ratio of \(\frac{\text{FWHMy}}{\text{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.

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.

Different possibility of graphics taken with the same set of images.

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.

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

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.

Right-click on a drawn selection to mass select/unselect or to zoom

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.

• Roundness: The roundness r is computed as the ratio of \(\frac{\text{FWHMy}}{\text{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.

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.

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

• 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

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.

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.

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.

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

   (1)\[ G(x,y) = B+Ae^{-\left(\frac{(x-x_0)^2}{2\sigma^2_x}+\frac{(y-y_0)^2}{2\sigma^2_y}\right)}.\]

2. An elliptical Moffat PSF fitting function defined as

   (2)\[ M(x,y) = B+A\left(1+\frac{(x-x_0)^2}{\sigma^2_x}+\frac{(y-y_0)^2}{\sigma^2_y}\right)^{-\beta},\]

where:

• \(B\) is the average local background.

• \(A\) is the amplitude, which is the maximum value of the fitted PSF.

• \(x_0\), \(y_0\) are the centroid coordinates in pixel units.

• \(\sigma_x\), \(\sigma_y\) are the standard deviation of the Gaussian distribution on the horizontal and vertical axes, measured in pixels.

• \(\beta\) 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:

• \(\text{FWHM}_x\) and \(\text{FWHM}_y\): The Full Width Half Maximum on the X and Y axis in pixel units. These parameters are calculated as follow:

  • \(\text{FWHM}_x = 2\sigma_x\sqrt{2\log 2}\).

  • \(\text{FWHM}_y = 2\sigma_y\sqrt{2\log 2}\).

  • It is possible to obtain the FWHM parameters in arcseconds units. This requires you fill all fields corresponding 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.

• \(r\): The roundness parameter. It is expressed as \(\text{FWHM}_x/\text{FWHM}_y\), with \(\text{FWHM}_x > \text{FWHM}_y\) the symmetry condition.

• Another parameters is also fitted in both Gaussian and Moffat models. This is the rotation angle \(\theta\), defined in the range \([-90°,+90°]\). The addition of this parameter implies a coordinate change where the \(x\) and \(y\) variables expressed in (1) and (2) are replaced by \(x'\) and \(y'\):

  (3)\[\begin{split} x' &= +x \cos\theta+y \sin\theta \\ y' &= -x \sin\theta+y \cos\theta.\end{split}\]

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 \(\beta = 1.4\).

Rotated Gaussian and Moffat function have \(\sigma_x=2\sigma_y\), \(\theta=45°\). For Moffat, \(\beta = 1.4\).

Star Profile with Gaussian and Moffat models. Several \(\beta\) values are tried. \(\beta = 10\) gives a profile very close to the Gaussian one.

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.

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.

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 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.

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.

• 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.

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

References

[Stetson1987]

Stetson, P. B. (1987). DAOPHOT: A computer program for crowded-field stellar photometry. Publications of the Astronomical Society of the Pacific, 99(613), 191.

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.

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.

Platesolving dialog

• 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.

Photometric Color Calibration tool

• 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.

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 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.

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.

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 (α, δ), parallaxes, 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 galaxies.

• 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

• 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).

Preferences with local catalogues

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.

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).

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.

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.

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.

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.

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.

Buttons for annotations

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.

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)

• 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

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.

Catalogue management in Preferences/Astrometry

The two user defined catalogues can also be purged (ie deleted) via the appropriate buttons.

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.

Local Catalogue (NOMAD) setup

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.

Deep sky objects from user and predefined catalogues

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

• 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

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.

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.

View with predefined/DSO/SSO

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 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.

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).

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).

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.

Example of exoplanet photometry in Siril.

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.

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.

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 \(B\cdot A\):

(1)\[ S = I + B\cdot A\]

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:

(2)\[ I = S - B\cdot A\]

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:

(3)\[ m = -2.5 \log_{10}\left(\frac{I}{I_0}\right)\]

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:

(4)\[ \operatorname{Var}(f(X)) = \left(\frac{df}{dx}\right)^2 \operatorname{Var}(X)\]

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.

(5)\[ \operatorname{Var}(aX + b) = a^2 \operatorname{Var}(X)\]

The second law defines the error of a logarithm of uncertain value X:

(6)\[ \operatorname{Var}(\log(\pm bX)) = \frac{\operatorname{Var}(X)}{\bar{X}^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:

(7)\[ \log_b(x) = \frac{\log_k(x)}{\log_k(b)}\]

Putting these two equations together we get:

(8)\[ \operatorname{Var}(\log_{10}(\pm bX)) = \frac{\operatorname{Var}(X)}{\bar{X}^2\,\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.

(9)\[ \operatorname{Var}(X + Y) = \operatorname{Var}(X) + \operatorname{Var}(Y)\]

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

(10)\[ SE_{\bar{X}} = \frac{s}{\sqrt{N}}\]

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 \(\sigma_{pxl}^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 \(\sigma_{pxl}^2\). For the variance of the first source of error we get:

(11)\[ \sigma_1^2 = A\,\sigma_{pxl}^2\]

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 \(\lambda\) as

(12)\[\lambda = I\,p\]

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.

(13)\[ \sigma_{ph}^2 = \operatorname{Var}(\operatorname{Pois}(\lambda)) = \lambda = I\,p\]

The variance is in photons, we have to convert it back to ADU to get the variance in units \(ADU^2\).

(14)\[ \sigma_2^2 = \frac{\sigma_{ph}^2}{p^2} = \frac{I\,p}{p^2} = \frac{I}{p}\]

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 \(\sigma_{pxl}^2\), the variance of sample mean is

(15)\[ s_{sky}^2 = \frac{\sigma_{pxl}^2}{n_{sky}}\]

where \(n_{sky}\) is the number of pixels in sky annulus.

From equation (9) we compute the variance of object's intensity as

(16)\[ \sigma_{ADU}^2 = \sigma_1^2 + \sigma_2^2 + A^2\,s_{sky}^2\]

Note, that in equation (2) the sky level is multiplied by A, so we have to multiply its variance by \(A^2\) - see the equation (16). Now, we use the law of error propagation for the logarithm adopted to match the formula of the Pogson's law.

(17)\[ \sigma_{mag}^2 = \left(\frac{-2.5}{I\,\log(10)}\right)^2\,\sigma_{ADU}^2\]

Putting equations (17) and (16) together, we can derive the standard error of the object's brightness in magnitudes as

(18)\[ \sigma_{mag} = \frac{1.08574}{I}\,\sqrt{\sigma_{ADU}^2}\]

Quick photometry

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).

Photometry results window.

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

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 the ratio of \(\frac{\text{FWHMy}}{\text{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 calculation 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:

   (1)\[ \text{SNR} = 10 \log_{10}\left(\frac{I}{N}\right)\]

   where I is the net intensity, proportional to the observed flux F and N the total of uncertainties as expressed in (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.

More details about the analyzed star. Click on the picture to enlarge.

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.

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.

In this example, 3 stars have been analyzed. The first one is used as variable. The others are references.

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 magnitude 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
  

  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.

  

  Photometry results window with true magnitude set.

• To unset the computed offset, just type

  unsetmag
  

  Siril command line

  unsetmag
  

  Resets the magnitude calibration to 0. See SETMAG

  
  

  Links: setmag

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

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.

Manual star selection

Start by selecting stars and running photometry analysis on the sequence for each, as explained here.

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.

The plot tab as showed right after the quick photometry on sequence.

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.

Switching to magnitude view make the Light Curve button sensitive.

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 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 of an exoplanet transit.

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.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:

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

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.

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

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.

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

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.

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.

Aberration inspector window showing differences in brightness.

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)

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.

One channel statistics for CFA image. The given values are not really relevant in this case.

Three channel statistics for CFA image.

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 made, statistics are computed within the selection. If -cfa is passed and the image is CFA, statistics are made on per-filter extractions

Estimators

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.

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.

Sigma

Also known as the standard deviation, noted \(\sigma\), 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.

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

avgDev

The Average Deviation, also called AAD for average absolute deviation or mean absolute deviation. In order to understand 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.

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.

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 \(\sqrt{BWMV}\)) of this value.

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 \(\sqrt{BWMV}\) could be used for scale. However, in order to give more robustness to the measures, the pixels more than \(6\times \text{MAD}\) away from the median are discarded. On this clipped dataset, the median and \(\sqrt{BWMV}\) are re-computed and used as location and scale estimators respectively. They are computed relative to the reference image of a sequence in Siril.

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.

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,

  

• 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.

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.

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.

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.

Script page of preferences. The script are loaded from the paths listed in the Script Storage Directories.

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.

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.

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.

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.

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
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

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.

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.

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, temperature 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)
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.

• 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

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:

• $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.

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.

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.

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.

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.

• 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 preprocessing 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.

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 arguments in order to calibrate the images during livestacking.

  Siril command line

  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

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

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

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.

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

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

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=]

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

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]

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.

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

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

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]

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.

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.

-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 }

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

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

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

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 -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 [-date] [-start=index] [-out=]

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. The additional argument -date enables sorting files with their DATE-OBS value instead of with their name alphanumerically

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

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.

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 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;

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

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

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

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

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".

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. 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

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

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]

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

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

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

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.

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.

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=]

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_"

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]

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

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

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.

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

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

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

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

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

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

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

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

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.

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 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.

- 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

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

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

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

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

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!

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.

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:

       "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.

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.