Interprétation d'entête

Le parsing est la capacité d'analyser, c'est-à-dire d'écrire des chaînes de caractères à partir des données contenues dans l'en-tête FITS. L'interprétation d’entêtes, introduit dans Siril 1.2.0, vise à donner plus de flexibilité au scripting en utilisant les données de l'entête pour écrire/lire des noms de fichiers ou des chemins. Pour l'instant, ceci est utilisé avec les commandes suivantes :

et bien sûr, leurs équivalents GUI.

Exemple de syntaxe

Nous allons prendre un exemple simple pour commencer. Supposons que vous ayez un fichier nommé :file:`light_00001.fit et que vous souhaitiez trouver un masterdark dans votre bibliothèque de masters qui corresponde aux caractéristiques de cette lumière. Comme vous avez choisi une convention pour nommer vos masterdark, vous savez que le bon dark doit être nommé comme suit :

DARK_"exposure"s_G"gain"_O"offset"_T"temperature"C_bin"binning".fit

avec les termes entre parenthèses remplacés par les valeurs lues dans votre en-tête d'image brute. Pour une exposition de 120s, une température de -10C, un gain/offset de 120/30 et un binning 1, le masterdark serait nommé :

DARK_120s_G120_O30_T-10C_bin1.fit

C'est exactement ce que cette fonctionnalité permet de faire. Si vous spécifiez le nom du dark avec les conventions expliquées juste après, vous pouvez dire à Siril d'ouvrir l'image, de lire son en-tête et d'utiliser ses valeurs pour écrire cette chaîne (et ensuite l'utiliser pour calibrer votre images).

Vous pouvez lire les informations contenues dans l'en-tête soit par la commande dumpheader, soit en faisant un clic droit sur une image ouverte et en sélectionnant Entête FITS.... Vous obtiendrez normalement une impression comme celle qui suit (certaines clés ont été supprimées par souci de concision) :

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

Le format utilisé pour spécifier le nom des darks serait alors :

DARK_$EXPTIME:%d$s_G$GAIN:%d$_O$OFFSET:%d$_T$SET-TEMP:%d$C_bin$XBINNING:%d$.fit

Tous les termes à analyser sont formés comme suit : $KEY:fmt$

Par exemple, $EXPTIME:%d$ sera interprété comme 120 si la brute a été exposée pendant 120s. Mais il sera interprété comme 120.0 si vous spécifiez $EXPTIME:%0.1f$, grâce au formateur %x.yf.

L'expression complète ci-dessus serait donc évaluée à :

DARK_**120**s_G**120**_O**30**_T**-10**C_bin**1**.fit

Dans ce premier exemple, nous n'avons utilisé que la conversion en nombres entiers avec %d. Mais il existe d'autres formatages conventionnels que vous pouvez utiliser :

  • %x.yf pour les nombres flottants

  • %s pour les chaînes de caractères

Note

Pour les chaînes de caractères, les espaces devant et derrière sont toujours supprimés, tandis que les espaces à l'intérieur des chaînes sont remplacés par des signes _. Exemple : $OBJECT:%s$ sera converti en Rosette_Nebula.

Vous pouvez aussi utilisé des formatages moins conventionnels :

  • Pour analyser une date à partir d'un mot clé d'en-tête date-heure, vous pouvez utiliser le format spécial non standard dm12, qui signifie date moins 12h. Dans l'en-tête ci-dessus, la clé DATE-OBS a pour valeur 2022-01-24T01:03:34.729. La valeur de $DATE-OBS:dm12$ serait convertie en 2022-01-23, ce qui correspond à la date du début de la nuit. Vous pouvez également utiliser le formateur spécial dm0 qui analysera simplement la date, sans soustraire 12h.

  • Pour analyser une date-time à partir d'une clé d'en-tête date-time, vous pouvez utiliser le format spécial non standard dt, qui signifie simplement date-time. Dans l'en-tête ci-dessus, le mot clé DATE-OBS a pour valeur 2022-01-24T01:03:34.729. La conversion de $DATE-OBS:dt$ se ferait alors en 2022-01-24_01-03-34.

  • Pour analyser les informations RA et DEC des mots clés d'en-tête OBJCTRA et OBJCTDEC, vous pouvez utiliser les formateurs spéciaux non standard ra et dec. Dans l'en-tête ci-dessus, les mots clés OBJCTRA et OBJCTDEC ont une valeur de 06 30 36 et +04 58 51 respectivement. $OBJCTRA:ra$_$OBJCTDEC:dec$ serait converti en 06h30m36s_+04d58m51s.

  • Pour analyser les informations RA et DEC à partir des mots clés d'en-tête RA et DEC, lorsqu'elles sont au format décimal, vous pouvez utiliser les formats spéciaux non standard ran et decn. Dans l'en-tête ci-dessus, les mots clés RA et DEC ont une valeur de 97.6960081674312 et 4.99212765957446 respectivement. La conversion de $RA:ran$_$DEC:decn$ serait 06h30m47s_+04d59m32s.

Un bon exemple de noms de fichiers pour un résultat d'empilement est l'expression suivante :

$OBJECT:%s$_$FILTER:%s$_$STACKCNT:%d$x$EXPTIME:%d$sec_G$GAIN:%d$_O$OFFSET:%d$_T$CCD-TEMP:%d$°C_$DATE-OBS:dm12$

en donnant quelque chose comme :

NGC_7023_L_57x120sec_G100_O50_T-9°C_2023-10-07

Pour tester la syntaxe, vous pouvez charger une image et utiliser la commande parse, comme rappelé ci-dessous.

Ligne de commande Siril

parse str [-r]
Analyse la chaîne de caractères str en utilisant les informations contenues dans l'en-tête de l'image actuellement chargée. Le but principal de cette commande est de débuguer l'interprétation d'entête des clés d'en-tête qui peuvent être utilisées dans d'autres commandes.
L'option -r spécifie que la chaîne doit être interprétée en mode lecture. En mode lecture, tous les caractères génériques définis dans la chaîne str sont utilisés pour trouver un nom de fichier correspondant au motif. Sinon, le mode par défaut est le mode écriture et les caractères génériques, le cas échéant, sont supprimés de la chaîne à analyser.

Si la chaîne str commence par le préfixe $def, elle sera reconnue comme un mot-clé réservé et recherchée dans les chaînes stockées dans gui_prepro.dark_lib, gui_prepro.flat_lib, gui_prepro.bias_lib ou gui_prepro.stack_default pour $defdark, $defflat, $defbias ou $defstack respectivement.
Le mot-clé $seqname$ peut également être utilisé quand une séquence est chargée

Trouver un fichier avec l'interprétation d'entête

Dans l'exemple ci-dessus, nous avons vu que nous pouvions trouver le nom d'un dark maître à partir des informations contenues dans l'en-tête de la brute à calibrer. C'est ce que l'on appelle dans la commande parse, le mode lecture.

Ce comportement est principalement utilisé en conjonction avec la commande/onglet calibrate. Dans l'option -dark= de la commande ou dans le champ Dark de l'interface graphique, vous pouvez utiliser la syntaxe décrite ci-dessus. Ainsi, vous êtes sûr que le dark correspondant sera récupéré pour calibrer les images. Il en va de même pour Bias et Flat. Vous pouvez, bien sûr, donner un chemin complet (ou relatif) vers le fichier. Et le chemin peut aussi contenir des expressions du même type.

Par exemple, pour les flats, vous pouvez vouloir spécifier le chemin d'accès à une bibliothèque, qui pourrait contenir des informations sur les filtres ou les télescopes, car vous pouvez avoir plusieurs configurations. Un chemin comme :

~/astro/masters/flats/$INSTRUME:%s$_$TELESCOP:%s$/$FILTER:%s$/FLAT_bin$XBINNING:%d$.fit

serait alors évalué comme :

~/astro/masters/flats/ZWO_ASI294MC_Pro_61EDPH/DualBand/FLAT_bin1.fit

et est une valeur valide pour l'entrée "Flat".

Bien sûr, si vous deviez écrire cette commande dans vos scripts ou dans le champ "Flat" de l'interface graphique à chaque fois que vous calibrez, cela pourrait devenir un peu fastidieux. C'est là que les mots-clés réservés viennent à la rescousse. Il y a 3 mots-clés réservés pour les maîtres :

  • $defdark

  • $defflat

  • $defbias

Leurs valeurs sont définies dans Préférences ‣ Pré-traitement section. Vous pouvez également les spécifier par le biais de scripts grâce à la commande set. Ils correspondent aux valeurs de gui_prepro.dark_lib, gui_prepro.flat_lib et gui_prepro.bias_lib.

Lorsque leurs valeurs sont définies et que vous avez choisi de les utiliser comme valeurs par défaut, elles seront affichées dans les champs de l'onglet Calibration. Vous pouvez également commencer à écrire vos scripts en utilisant ces mots-clés. L'étape de calibration d'un nouveau script générique pour une caméra couleur pourrait ressembler à ceci :

calibrate light -dark=$defdark -cc=dark -flat=$defflat -cfa -equalizecfa -debayer

Cela permet de prélever vos masters directement dans vos bibliothèques et de s'assurer que vous ne les mélangez jamais pendant l'étape d'étalonnage.

Écriture d'un fichier avec interprétation de l'entête

Maintenant, bien qu'il soit pratique de pouvoir trouver les fichiers, il serait tout aussi utile d'utiliser cette syntaxe pour stocker vos fichiers pendant l'empilement. C'est exactement ce à quoi sert le mode écriture. La syntaxe peut être utilisée dans le champ -out= des commandes stack et stackall, ou dans le champ correspondant dans l'interface graphique.

Imaginons que vous vouliez écrire un script générique qui prépare vos master darks à chaque fois que vous renouvelez votre bibliothèque. Dans la ligne stack du script, vous pourriez écrire :

stack dark rej 3 3 -nonorm -out=$defdark

Cette ligne garantit que le masterdark résultant sera stocké au bon endroit avec le nom de fichier correct qui peut ensuite être récupéré pour calibrer vos brutes.

Afin d'introduire encore plus de flexibilité avec les commandes stack, il y a deux mots-clés réservés supplémentaires :

  • $defstack

  • $sequencename$

Comme pour les maîtres par défaut, $defstack est configuré dans la même section des Préférences, ou avec une commande set sur gui_prepro.stack_default. Par exemple, supposons que vous ayez défini $defstack comme :

Result_$OBJECT:%s$_$DATE-OBS:dm12$_$LIVETIME:%d$s

La ligne de script :

stack r_pp_light rej 3 3 -norm=addscale -output_norm -out=$defstack

sauvegarde le résultat de l'empilement comme :

Result_Rosette_Nebula_2022-01-24_12000s.fit

Depuis Siril 1.2.0, le nom par défaut pour l'empilement est défini comme $sequencename$stacked (le signe _ est ajouté s'il n'est pas présent). Ce comportement est similaire à celui des versions précédentes, sauf qu'il est maintenant explicite que l'interprétation de l'entête est utilisée.

Utilisation des caractères de remplacement

Il se peut que vous vouliez utiliser une valeur clé dans le nom de vos masters qui ne correspond pas à la valeur clé des images à calibrer. Avec un exemple, ce sera peut-être un peu plus clair. Disons que vous voulez, dans le nom de vos masters, enregistrer leur temps d'exposition. Quelque chose comme :

FLAT_1.32s_Halpha_G120_O30_bin1.fit

Si vous mettez un champ $EXPTIME:%0.2f$ dans $defflat, cela se terminera par une erreur à l'étape de calibration. Tout simplement parce que la clé EXPTIME sera lue à partir de l'image brute à calibrer, et non d'un flat.

Pour faire face à cette situation, vous pouvez utiliser des caractères génériques dans les expressions à analyser :

FLAT_$*EXPTIME:%0.2f$_$FILTER:%s$_G$GAIN:%d$_O$OFFSET:%d$_bin$XBINNING:%d$

Notez le symbole * placé juste avant EXPTIME.

La signification de ce symbole est la suivante :

  • En mode écriture, c'est-à-dire lors de l'empilement de votre flat maître, le champ EXPOSITION sera utilisé pour former le nom du fichier à sauvegarder. Dans l'exemple ci-dessus, vous sauvegarderez effectivement le fichier FLAT_1.32s_Halpha_G120_O30_bin1.fit.

  • En mode lecture, donc lors de l'étalonnage de vos brutes, le champ EXPOSURE sera remplacé par *. Lors de la recherche d'un tel fichier, Siril récupérera tous les fichiers qui correspondent au modèle FLAT_*_Halpha_G120_O30_bin1.fit. Avec un peu de chance, votre convention de nommage est suffisamment robuste pour qu'il ne trouve qu'un seul fichier correspondant et l'utilise pour le calibrage.

Avertissement

Dans le cas où Siril trouve plus d'un fichier en "mode lecture", il émettra un avertissement dans la console et sélectionnera le fichier le plus récent. Comme cela peut ne pas produire le résultat souhaité, vous devriez reconsidérer votre convention de nommage si cela se produit.

Gestion des doublons

Dans certains cas, il existe plusieurs mots-clés pour la même valeur. En effet, les développeurs de logiciels sont libres d'utiliser les mêmes mots-clés ou d'en créer de nouveaux. Siril tente donc de reconnaître et de gérer les doublons. Voici un tableau récapitulatif des doublons connus. Si un fichier contient des mots-clés dits « alternatifs », alors Siril stockera la valeur dans la version « primaire ».

Mot-clé principal

Alternatif

MIPS-HI

CWHITE

MIPS-LO

CBLACK

PROGRAM

SWCREATE

IMAGETYP

FRAMETYP

EXPTIME

EXPOSURE

FILTER

FILT-1

FOCALLEN

FOCAL

CENTALT

OBJCTALT

CENTAZ

OBJCTAZ

XBINNING

BINX

YBINNING

BINY

XPIXSZ

XPIXELSZ, PIXSIZE1, PIXSIZEX, XPIXSIZE

YPIXSZ

YPIXELSZ, PIXSIZE2, PIXSIZEY, YPIXSIZE

CCD-TEMP

CCD_TEMP, CCDTEMP, TEMPERAT, CAMTCCD

OFFSET

BLKLEVEL

CVF

EGAIN

FOCPOS

FOCUSPOS

FOCTEMP

FOCUSTEM

STACKCNT

NCOMBINE

SITELAT

SITE-LAT, OBSLAT

SITELONG

SITE-LON, OBSLONG