Application fits2caom2

fits2caom2 est un logiciel JAVA dont la principale fonction et d'essayer de traduire l'entête d'un fichier FITS dans un fichier XML qui représente un enregistrement CAOM. Un enregistrement CAOM doit être créé et ingéré dans l'archive du CAOM afin de permettre la recherche des observations via les engins de recherche du CCDA (TAP ou Recherche Avancée).

Ce document est surtout utile aux utilisateurs qui prévoient maintenir ou ingérer de nouvelles observations au CCDA et qui veulent utiliser fits2caom2 pour créer les enregistrements CAOM.

Les instructions qui suivent ne s'appliquent qu'aux architectures LINUX ou OSX et requirent l'installation JAVA JDK version 8.

Téléchargement

Lien

Installation

Le téléchargement et l’expansion du fichier TAR ci-haut créera un fichier JAVA .jar, les classes nécessaires à son éxécution en plus d’une scripte d’éxécution principale nommée fits2caom2. Pour ce faire veuillez suivre ces instrunctions simples:

• Création d'un répertoire d'installation: mkdir fits2caom2
• Télécharger et décoder le fichier tar dans ce répertoire: cd fits2caom2 ; tar xzf ../fits2caom2.tgz
• Créer une variable d'environnemt requise: CADC_ROOT qui doit pointer au répertoire où vous avez installé fits2caom2. Si votre shell est bash:</p> export CADC_ROOT=`pwd`

  pour (t)csh:

  setenv CADC_ROOT `pwd`

Il est facile de vérifier si l'installation s'est effectuée correctement. Il suffit d'exécuter la commande suivante:
./scripts/fits2caom2 --help

Si vous avez des difficultés à installer fits2caom, veuillez contacter le CCDA.

Usage

La première action de fits2caom2 est d'examiner l'entête FITS de votre fichier d'entrée et de tenter de créer un enregistrement CAOM. Il est presque sur que votre première tentative échouera car certains mots clés obligatoires ne seront pas trouvés ou seront erronés. Nous verron par la suite la façon de corriger cette situation.

Voici un exemple d'un utilisateur qui exécute fits2caom2 sur un fichier FITS multi-extension (MEF) qui représente une observation obtenue par la caméra megaprime au TCFH:

fits2caom2 --collection=CFHT \
           --observationID=1615920 \
           --productID=1615920o \
           --uri=ad:CFHT/1615920o \
           --local=1615920o.fits  \
           --out=1615920o.xml

Cette dernière commande exige quelques explications.

• --collection Est le nom de la Collection dans le système d'archive du CCDA. La valeur de Collection vous sera fourni par le CCDA et sera disponible dans l'engin de recherche du CCDA
• --observationID Est une dénomination unique dans une Collection donnée et essentiellement représente une observation. Par exemple, cette valeur est fixée par un odomètre par le système d'acquisition du télescope TCFH et identifi uniquement chacune des observations.
• --productID permet de définir uniquement chacun des Plane. Voici comment nous identifions un nouveau Plane pour les observations non calibrées, ou brutes, du TCFH. Ils représentent les observations pour lesquelles la lettre 'o' est rajoutée en suffixe à l'odomètre qui identifie une observation. Cette valeur n'a pas à être unique pour une collection donnée mais l'utilisation d'un nom unique aide une éventuelle recherche si désirée.
• --uri C'est avec ce paramètre qu'il nous est permis d'identifier les différents Artifact qui appartiennent à un productID. C'est une simple liste de fichiers séparés par une virgule. Les fichiers sont habituellement identifiés avec leur location dans les archives du CCDA dans le format suivant: ad:{COLLECTION}/{filename}. où COLEECTION est le nom de la collection et filename, le nom de fichier utilisé lors de l'ingestion dans l'archive avec cadc-copy.
• --local permet de spécifier l'endroit où se situe le fichier FITS sur votre ordinateur sur lequel vous roulez fits2caom pour contruire l'enregistrement CAOM pour cette observation. Si cette option est inexistante, fits2caom utilsera les informations spécifiées par --uri pour localiser le fichier.
• --out est le nom du fichier qui contiendra l'enregistrement CAOM résultant en format XML.
</ul>

Après la création de votre enregistrement CAOM, il est possible (et souvent requis) d'ajouter des plans additionnels en exécutant à nouveau code>fits2caom2</code> avec cette fois-ci un fichier d'entrée XML et en spécifiant les nouvelles variables productID, uri et local. Un nouveau fichier XML sera alors produit.

fits2caom2 --collection=CFHT \
--observationID=1615920 \
--productID=1615920p \
--uri=ad:CFHT/1615920p \
--local=1615920p.fits  \
--in=1615920o.xml \
--out=1615920.xml 

• --in permet de spéficier le nom d'un document XML (enregistrement CAOM) auquel on veut modifier ou rajouter, ou même enlever des informations en exécutant fits2caom2

Maintenant le fichier XML comprend les entrées CAOM pour deux Plane (1615920o and 1615920p)

D'autres options sont disponibles pour permettre d'augmenter les informations qui pourraient (for probablement) ne pas se retrouver dans vos entêtes FITS ou de remplacer le comportement de fits2caom2 si ce n'est pas adéquat.

--config=camera.config

Même si fits2caom2 construit avec une vision astronomique, il est facile de démontrer qu'il est impossible de prévoir de façon général les différents mots clés utilisés automatiquement. Pour aider fits2caom2 à produire des enregistrements corrects, il est possible de spécifier la correspondance entre les mots clés FITS et les variables CAOM via un fichier de configuration. Voici un exemple qui remplace la valeur CAOM camera.config pour l'archive MegaPrime du TCFH:

Observation.telescope.geoLocationX = telescope.geoLocation
Observation.type = OBSTYPE
Chunk.naxis = ZNAXIS,NAXIS
Chunk.energyAxis = getEnergyAxis()
Chunk.energy.axis.axis.ctype = CTYPE{energyAxis}
.
.
.

Les exemples précédents présentent la façon de spécifier les valeurs dans le fichier de configuration:

1. Les valeurs sont spécifiées dans un fichier appelé default.config (voir prochaine section)
2. La référence à une ou plusieurs clés FITS ( Si il y a un doublon, c'est la première occurence qui est conservée)
3. Un appel à une fonction spéciale de fits2caom2
4. Une référence à un mot clé FITS via une variable qui est définie autre part dans le fichier default.config

Quelque fois l'évaluation des variables est faites via une logique quelque peu cryptique et l'usager peut remplacer cette variable par une valeur fixe pour simplifier la lecture. Veuillez notez qu'il n'est pas possible de définir sa propre fonction pour convertir des clés FITS en commande CAOM.

On utilise l'option --dumpconfig pour obtenir la liste des variables utilisées par CAOM.

--default=camera.default

L'exécution directe de fits2caom2 va produire certainement un enregistrement CAOM non valide. Il est presque impossible d'interpréter automatiquement les bonne valeurs en utilisant les entêtes FITS. Il est donc essentiel de fournir à fits2caom2 de plus amples informations. La première façon est de composer un fichier qui contient des valeurs de défaut pour quelques paramètres, comme un entête FITS supplémentaire. Le fichier doit contenir les équivalences entre les mots clés CAOM et la correspondance soir via une valeur FITS ou une valeur fixe. L'exemple suivant permet de comprendre le principe:

algorithm.name = exposure

telescope.geoLocationX = -5464228.6
telescope.geoLocationY = -2493778.2
telescope.geoLocationZ = 2150937.8
telescope.name =  CFHT 3.6m

provenance.name = ELIXIR
provenance.producer = CFHT
provenance.project = STANDARD PIPELINE
provenance.reference = http://www.cfht.hawaii.edu/Instruments/Elixir/

plane.dataProductType=image

CUNIT1 = deg
CUNIT2 = deg
CRDER1 = 0.0000278
CRDER2 = 0.0000278
CSYER1 = 0.0000278
CSYER2 = 0.0000278

CTYPE3 = TIME
CUNIT3 = d
CRDER3 = 0.0000001
CSYER3 = 0.0000001

CTYPE4 = WAVE
CUNIT4 = Angstrom
NAXIS4 = 1
CRPIX4 = 1
SPECSYS = TOPOCENT
SSYSOBS = TOPOCENT
SSYSSRC = TOPOCENT
CRDER4 = 1.0
CSYER4 = 1.0

Les valeurs des paramètres spécifiés dans le fichier camera.default ne seront pas recherchée dans les entêtes par fits2caom.

Veuillez noter les valeurs des mots clés CTYPE?. C'est un peu étrange mais pour que le modèle CAOM soit complet, il nous faut ajouter deux axes supplémentaires: un axe temporel (TIME) et un axe d'énergie (WAVE). La dimension de ces axes est exactement un seul pixel et permet de spécifier les 4 dimensions de nos fichiers d'observation (les deux dimensions spatiales, un axe temporel et un axe d'énergie). Dans le cas d'une image 2D simple, les axes supplémentaires seront les axes 3 et 4 et seront déterminés dans le modèle en utilisant les fonctions getEnergyAxes() et getTimeAxes() respectivement.

--override=camera.override

Certaines valeurs que fits2caom2 tentera d'utiliser seront non valides. Pour ces dernières, il est possible d'avoir un main un fichier spécial appelé "override" qui permettra de forcer l'usage de ces valeurs plutôt que celles découvertes par l'uage de fits2caom2. Essentiellemtn via ce fichier vous configurer fits2caom de ne pas utiliser les valeurs des entêtes FITS pour ces valeurs.

Une fois que vous avez en main ces fichiers de configuration supplémentaires, vous pouvez procédez en utilisant la commande suivante.

fits2caom2 --collection=CFHT \
--observationID=1615920 \
--productID=1615920p \
--uri=ad:CFHT/1615920p \
--local=1615920p.fits  \
--config=camera.config \
--default=camera.default \ 
--override=camera.override \
--in=1615920o.xml \
--out=1615920.xml