LIB MC
une librairie de calculs de mécanique céleste
version 20010717
Alain KLOTZ

Manuel de l'utilisateur

Libmc est une librairie d'extension Tcl qui ajoute des fonctions utilitaires de mécanique céleste. Ce guide de l'utilisateur s'adresse aux programmeurs de scripts Tcl qui désirent utiliser les fonctions de libmc. Les fonctions faisant appel aux "buffer" de AudeLA ne peuvent être employées qu'avec la plate forme AudeLA.

1. Généralités

1.1. Chargement de la librairie dans l'interpréteur Tcl

Le chargement de la librairie libmc dans l'interpréteur Tcl se fait simplement par la commande :

load libmc[info sharedlibextension]

dans l'interpréteur Tcl. La commande [info sharedlibextension] signifie à l'interpréteur Tcl d'ajouter, automatiquement, les lettres correspondant au suffixe .dll ou .so en fonction du système d'exploitation.

Si l'interpréteur retourne le message d'erreur : couldn't load file "libmc": invalid argument, c'est que le fichier de librairie libmc (libmc.dll sous Windows et libmc.so sous Linux) n'est pas placé dans le répertoire courant de l'interpréteur (cf. fonctions pwd et cd de Tcl).

1.2. Principe général des fonctions de MC

Les fonctions de libmc, ajoutées à Tcl, commencent toutes par le préfixe mc_ de façon à les reconnaître. Par exemple, la fonction mc_date2jd convertit une date en jour julien. Le paramètre de la fonction mc_date2jd est une variable Tcl permettant de définir la date sous diverses formes. Par exemple, pour retourner le jour julien de l'instant présent, le paramètre est now. La fonction s'écrira donc :

mc_date2jd now

Si l'interpréteur retourne le message d'erreur : invalid command name "mc_date2jd", c'est que la librairie libmc n'a pas été chargée correctement
 

2. Guide de référence des fonctions de MC

Les fonctions Tcl, ajoutées par MC proposent une vaste étendue de possibilités. En respect avec la syntaxe Tcl, chaque fonction se définit par des paramètres obligatoires, des paramètres facultatifs et des paramètres optionnels. Ces paramètres doivent répondre à certaines contraintes de syntaxe. C'est pour cela que nous commencerons par définir les "types" des paramètres utilisés spécifiquement par MC avant d'aborder la liste des fonctions.

Les paramètres des fonctions de MC sont standardisés pour permettre une utilisation souple. Ainsi, Mc définit les types de paramètres suivants :

Par exemple, la syntaxe de la fonction mc_date2jd est : date2jd Date
 

2.1. Définition des types de paramètres pour MC :

2.1.1. Les types Date et ListDates

La définition d'une date peut être faite de plusieurs façons différentes : N.B. Les mots NOW, NOW0 et NOW1 peuvent être écrits indifféremment en majuscule ou en minuscule.

Le type ListDates de MC signifie une liste Tcl d'éléments de type Date. Par exemple :

{2000 1 1} {2000 1 2} 2451056.4563 {2000-01-03T00:00:00} now

2.1.2. Le types Angle et ListAngles

La définition d'un angle peut être faite de plusieurs façons différentes. Ci dessous, quelques exemples : Le type ListAngles de MC signifie une liste Tcl d'éléments de type Angle. Par exemple :

{45d34} {-45 38 6.4} {1h30m} {2 r}

2.1.3. Les types Object et ListObjects

La définition d'une planète ou d'une étoile est réalisée sous la forme d'une liste dont les éléments sont définis ainsi : N.B. Les mots définissant Format et Data peuvent être écrits indifféremment en majuscule ou en minuscule.

Par exemple, la planète Jupiter est définie par la liste

{jupiter internal}

ou plus simplement par le mot Jupiter puisque Internal est pris par défaut. En revanche, pour l'astéroïde 1997DQ :

{1997DQ Bowellfile astorb.dat}

Le type ListPlanets signifie que le paramètre Name peut être une liste de planètes ou bien * si l'on souhaite toutes les planètes définies dans Data. Par exemple :

{ { {1} {6809} {10222} {1997DQ} } Mpcfile mpcorb.txt }

Ou encore, pour définir les neuf planètes du système solaire, ainsi que le Soleil et la Lune :

{ * Internal}

que l'on peut simplement écrire * car Internal est la valeur par défaut.

2.1.4. Le type Home

Le type Home permet de localiser un point sur la Terre de façon à calculer une éphéméride topocentrique par rapport à ce site, c'est à dire tenant compte des effets de la parallaxe. La définition d'un site est réalisée sous la forme d'une liste dont les éléments sont définis ainsi : En fonction de la définition du format, les autres éléments ont des sens différents : N.B. Les mots définissant Format peuvent être écrits indifféremment en majuscule ou en minuscule.

Par exemple, pour l'observatoire de Paris, situé à 2.3375 degrés est de greenwich avec rho*sin(phi') = 0.74918 et rho*cos(phi') = 0.65950, on écrira :

{ MPC 2.3375 0.65950 0.74918 }

Autre exemple, pour un observateur situé à la longitude 3 degrés ouest, latitude de 46 degrés nord et une altitude 456 mètres :

{ GPS 3 W 46 456 }

2.1.5. Le type Field

Le type Field permet de définir le champ de vue d'un système optique réalisant une projection gnomonique (image CCD par exemple).  La définition d'un champ est réalisée sous la forme d'une liste dont les éléments sont définis ainsi : En fonction de la définition du format, les autres éléments ont des sens différents : N.B. Les mots définissant Format et leurs arguments (NAXIS1, etc.) peuvent être écrits indifféremment en majuscule ou en minuscule.

Par exemple, pour définir un champ centré sur 12h00m et 15d avec un télescope de focale 2.5 mètres, une caméra de 768x512 pixels de 9 microns de côtés, on écrira :

{ OPTIC NAXIS1 768 NAXIS2 512 FOCLEN 2.5 PIXSIZE1 9e-6 PIXSIZE2 9e-6 CROTA2 0 RA 180 DEC 15 }
 

2.1.6. Les types Format et ListFormat


La définition d'un format de sortie est réalisée en indiquant le nom de la donnée à écrire. Les valeurs possibles pour Format sont :

N.B. Les mots définissant  le type Format peuvent être écrits indifféremment en majuscule ou en minuscule.

Le type ListFormat permet d'écrire la liste des paramètres que l'on veut en sortie. Par exemple, pour avoir le nom, la date et la magnitude d'un objet, on écrira la liste suivante :

{ OBJENAME YEAR MONTH DAY MAG }

2.1.7. Le type d'option -constraint

Le type -constraint s'applique aux options. Il permet d'exclure des astres situés hors de valeurs acceptables. Il existe deux syntaxes correspondantes aux cas suivants : La liste des contraintes possibles est la suivante : N.B. Les mots définissant les types "Option" et leurs arguments peuvent être écrits indifféremment en majuscule ou en minuscule.

Note : en ce qui concerne les options azimuth et ha, la définition de > et < est un peu différente. -ha< 15 signifie de garder tous les astres qui ont un angle horaire inférieur à 15 degrés du méridien (de part et d'autre). Idem pour azimuth.

Par exemple, si  l'on souhaite garder uniquement les astres plus brillants que la magnitude 12 mais plus faible que la magnitude 10, de déclinaison supérieure à -15 degrés, de hauteur supérieure à 30 degrés, on écrira les options suivantes :

-mag< 12 -mag> 10 -dec> -15 -altitude> 30

2.2. Fonctions d'extension Tcl de MC

On trouvera ci-après la liste des fonctions MC accessibles depuis l'interpréteur Tcl.

2.2.1. Ephémérides

La fonction de génération d'éphémérides s'appelle mc_ephem.

mc_ephem ListObjects ?ListDates? ?ListFormat? -constraint Value -topo Home

Par défaut, ListDate=NOW et ListFormat={ OBJENAME RA DEC}

En retour, on obtient une liste dont chaque élément contient des données sous la forme définie par ListFormat. Le dernier élément de la liste de sortie est différent. Il contient des informations sur le calcul effectué. Les catalogues d'étoiles de ListObject ne sont pas pris en compte. Dans les options -contrainst, magr et magb sont sans effet.

Dans le cas particulier d'objets de type astéroïdes de la base de Bowell ou du MPC, il y a deux options supplémentaires :

Exemples : Pour calculer l'éphéméride d'un astre pour plusieurs dates, il est utile de générer la ListDates à partir de la fonction mc_date2listdates.

2.2.2. Astres dans un champ

La fonction permettant de lister les astres dans un champ d'image CCD est mc_readcat.

mc_readcat Field ListObjects Output -constraint Value -objmax Value -date Date -topo Home

Le paramètre obligatoire Output sert à déterminer si les données de sortie seront écrites dans un fichier ou sous la forme d'une liste en retour. Les valeurs autorisées de Output sont les suivantes :

L'option -objmax sert à déterminer un nombre maximum d'objets dans la liste de sortie. Par défaut cette valeur vaut 1000.

Seules les options -contrainst, magb et magv sont actives.

L'option -date permet de fixer une date pour le cas de position planétaires (NOW par défaut).

L'option -topo permet de fixer un site pour le cas de position planétaires (géocentrique par défaut).

Le format de sortie est figé : {RA DEC MAGB MAGR X Y OBJENAME}. Le champ OBJENAME n'est rempli que pour les planètes. Le dernier élément de la liste de sortie est différent. Il contient des informations sur le calcul effectué.

Exemples :

2.2.3. Utilitaires de conversion d'angles

mc_angle2deg Angle : retourne l'angle en degrés décimaux
mc_angle2rad Angle : retourne l'angle en radians
mc_angle2dms Angle ?limit? ?nozero|zero? ?subsecdigits? ?auto|+? ?list|string? : retourne l'angle sous forme degrés,minute et seconde d'angle. Le résultat est retourné entre 0 et 360 degrés. L'option limit (=360 par défaut) permet de limiter le domaine d'angle. Si l'angle est supérieur à limit alors il est retourné négatif. Pour une déclinaison on imposera limit à 90. L'option nozero|zero sert à imposer que le format de sortie ajoute des zéros devant les chiffres (=nozero par defaut). L'option subsecdigits sert à fixer le nombre de digits retournés après les secondes. L'option auto|+ sert à imposer le retour du signe devant le résultat (=auto par défaut donc pas de signe imposé). L'option list|string sert à fixer le format de sortie sous la forme d'une liste (trois éléments {12 56 34.234} par exemple) ou bien sous la forme d'une seule chaîne (12d56m34s234 par exemple).
mc_angle2hms Angle ?limit? ?nozero|zero? ?subsecdigits? ?auto|+? ?list|string? : retourne l'angle sous forme heure,minute et seconde de temps. Le résultat est retourné entre 0 et 24 heures. L'option limit (=360 par défaut) permet de limiter le domaine d'angle (limit doit être exprimé en degrés). Si l'angle est supérieur à limit alors il est retourné négatif. L'option nozero|zero sert à imposer que le format de sortie ajoute des zéros devant les chiffres (=nozero par defaut). L'option subsecdigits sert à fixer le nombre de digits retournés après les secondes. L'option auto|+ sert à imposer le retour du signe devant le résultat (=auto par défaut donc pas de signe imposé). L'option list|string sert à fixer le format de sortie sous la forme d'une liste (trois éléments {12 56 34.234} par exemple) ou bien sous la forme d'une seule chaîne (12h56m34s234 par exemple).
mc_angle2lx200dec Angle ?-format long|short? : retourne l'angle au format déclinaison (Sd) du protocole LX200. L'option format permet de choisir l'écriture longue ou courte défini dans le protocole.
mc_angle2lx200ra Angle : ?-format long|short? retourne l'angle au format acsension droite (Sr) du protocole LX200. L'option format permet de choisir l'écriture longue ou courte défini dans le protocole.
mc_anglesep Listangles ?Units?: retourne l'angle de séparation et l'angle de position. La liste doit compter 4 angles définis dans l'ordre suivant : Ra1 Dec1 Ra2 Dec2). Le résultat est retourné en degrés par défaut. Pour avoir un résultat en radian ajouter Unit=Radian.
mc_angles2ultima2000 Angle Angle : retourne les deux angles RA DEC en une seule chaîne au format "16bit-angles" du protocole Ultima2000 .
mc_ultima20002angles Ultima2000_string : retourne une liste RA DEC (en degrés) à partir d'une seule chaîne au format "16bit-angles" du protocol Ultima2000.

mc_radec2altaz Angle_ra Angle_dec Home Date : retourne une liste des quatre paramètres utiles pour le système altazimutal : Azimut, Hauteur, Angle horaire et Angle parallactique.

mc_anglescomp Angle1 operand Angle2 : effectue une operation arithmétique (+,-,*,/,modulo) sur deux angles.

Les fonctions suivantes sont obsolètes mais restent utilisables.

mc_deg2dms Degrees : retourne une liste Dd Mm Ss.sss
mc_deg2hms Degrees : retourne une liste Hh Mm Ss.sss
mc_dms2deg Dd Mm Ss.sss : retourne une liste Degrees
mc_hms2deg Hh Mm Ss.sss : retourne une liste Degrees

mc_sepangle Ra1 Dec1 Ra2 Dec2 ?Units? : retourne l'angle de séparation et l'angle de position. Les angles (en entrée et en sortie) sont comptés en degrés par défaut, en radians si Units=Radian.
 

2.2.4.Utilitaires de conversion de dates

mc_date2jd Date : retourne le jour julien du paramètre du type Date.
mc_date2ymdhms Date : retourne la date en clair Yyyy Mm Dd Hh Mm Ss.sss à partir du type Date.
mc_date2lst Date Home : retourne le temps sidéral sous la forme Hh Mm Ss.sss à partir des paramètres de type Date et du type Home.
mc_date2listdates Date DateStep NbSteps : retourne une ListDates à partir d'une date incrémentée NbSteps fois du pas DateStep (en jours).
mc_date2iso8601 Date: transforme une date en format d'entete FITS. Utile pour ajouter l'info DATE-OBS à une entete FITS.
mc_datescomp Date Operand days : effectue une opération arithmetique à partir d'une date. Utile pour calculer le temps de pose milieu de l'image.

Exemples :

2.2.5. Utiltaires d'astrométrie

mc_buf2field Numbuffer : retourne une liste Field de paramètres optiques à partir de l'entête FITS de l'image du buffer numéro Numbuffer.
mc_xy2radec x y Field : retourne une liste au format {RA DEC}à partir des coordonnées x et y.
mc_radec2xy ra dec Field : retourne une liste au format {X Y}à partir des coordonnées ra et dec.
mc_precessradec ListAngles Date_eq1Date_eq2 ?Listangles_proper? : Retourne une liste d'angles en degrés (Ra et Dec) corrigés de la précession à partir des coordonnées de Listangle au format {ra dec}de l'équinoxe Date_eq1 vers l'équinoxe Date_eq2. Il est possible d'ajouter les mouvements propres annuels par l'intermédiaire de Listangles_proper.

mc_listradec Field Mosaic ComPix : Génère une liste de listes {X Y RA DEC} à partir d'un champ de type Field, en faisant une mosaïque définie par le paramètre Mosaic avec un recouvrement de ComPix pixels entre chaque champ. La mosaïque peut être générée de différentes façons :

9 2 3
8 1 4
7 6 5
Si Parity=0 alors tous les champs seront pointés (valeur par défaut).
Si Parity=1 alors seuls les champs d'indice impairs seront pointés
Si Parity=2 alors seuls les champs d'indice pairs seront pointés
Exemples :