Siril:FITS orientation

This page is now deprecated. Please refer to the new documentation at siril.readthedocs.io.

Orientation of FITS images

The FITS standard is a container that describes how to store image data and meta-data. 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.

Note

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 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: File:Bayer test pattern v6.tar.gz.