LIB MC
a library designed for celestial mechanics
version 20000402
Alain KLOTZ
User manual
Libmc is a Tcl extension library which adds functions concerning celestial
mechanics. This user guide is adressed to users of Tcl scripts who want
to use the libmc functions. Functions of libmc which require AudeLA "buffer"
can be used only with the AudeLA platform.
1. Introduction
1.1. Loading the library in a Tcl interpreter
To load the libmc library in a Tcl interpreter, use the following function
:
load libmc (for Windows)
load bin/libmc.so (for Linux)
in your current Tcl interpreter.
If the interpreter returns the error message : couldn't load file "libmc":
invalid argument, it means that the file of the libmc library (libmc.dll
with Windows and libmc.so with Linux) is not placed in the current folder
of the interpreter (cf. pwd and cd function of Tcl).
1.2. General principles of Mc functions
Every libmc function, added to Tcl, begins with the prefix mc_ in order
to be easily reconizable. For instance, function mc_date2jd converts a
date in a julian day. The parameter of the function mc_date2jd is a Tcl
variable which defines the date under differents formats. For exemple,
in order to compute the julian day of the present time, the parameter is
now. The syntax should be :
mc_date2jd now
If the interpreter returns the error message : invalid command name
"mc_date2jd", it means that the libmc library was
not loaded correctly.
1.3. Few examples
jlkhkjhkjh:
2. Reference guide for MC functions
The Tcl functions, added by MC, give many possibilities. According to the
Tcl syntax, every function is followed by mandatory parameters and ended
by optional parameters. These parameters must respect some constraints.
MC used specific "types" of parameters. They are listed below :
-
Date : to define a date
-
Angle : to define a angle
-
Object : to define a planet or a star.
-
Home : to define a a location on the Earth surface
-
Field : to define the field of view of an image
-
Format : to define an output format of values.
-
-constraint : to define a constraint option.
For exemple, the syntax of the function mc_date2jd is : date2jd Date
2.1. Definition of parameter types for MC :
2.1.1. Types Date and ListDates
the definition of a date can be writed by differents forms :
-
jd : a floating number upper or equal to 1000000 defines a julian date
-
mjd : a floating number lower to 1000000 defines a modified julian date
(jd - 2400000.5)
-
NOW : the word now takes the date and the time from the operating system.
-
NOW0 : the word now0 takes the date and the time at 0h a.m. from the operating
system
-
NOW1 : the word now1 takes the date and the time at 24h p.m. from the operating
system
-
{year month day h m s} : a gregorian date as a calendar. It is possible
to use floating numbers. For instance {2001 12 23.567}.
-
yyyy-mm-ddThh:mm:ss.ss : a gregorian date coded as the format DATE-OBS
of a header FITS
N.B. Words NOW, NOW0 et NOW1 can be written uppercase or lowercase without
incidence.
The type ListDates of MC defines a Tcl list of elements of type Date.
For exemple :
{2000 1 1} {2000 1 2} 2451056.4563 {2000-01-03T00:00:00} now
2.1.2. Types Angle and ListAngles
An angle can be written by many ways. Some following exemples show these
possibilities :
-
45°34'28" :
-
45d34m28s : is equal to 45°34'28"
-
45d34m28s9 : is equal to 45°34'28.9"
-
45d34 : is equal to 45°34'
-
45.34 : is interpreted as 45.34 décimal degrees.
-
-45d34.5 : is interpreted as -45°34'30"
-
1h30m : is interpreted as 22.5 decimal degrees (1 hour is equal to 15 degrees).
-
1.57r : is interpreted as 1.57 radians.
-
{45 34 28.4} : is interpreted as 45d34m28.4s
-
{1 30 h} : is interpreted as 1h30m.
-
{1.57 r} : is interpreted as 1.57 radians
The type ListAngles of MC defines a Tcl list of elements of type Angle.
For exemple :
{45d34} {-45 38 6.4} {1h30m} {2 r}
2.1.3. Types Object and ListObjects
A planet or a star can be defined by a list of elements defined (by order)
:
-
Name : character string which contains the name of the objects (planets
or stars). A * is interpreted as every objects.
-
Format : origin of orbital data. Possible values are :
-
INTERNAL : (default) if Name is the name, in english, of a solar system
planet (Mercury, ..., Pluto, Sun, Moon).
-
BOWELLFILE : to read data in the astorb.dat file of the Lowell observatory.
-
MCPFILE : to read data in the Mpcorb file of the Minor Planet Center
-
ASTROMMICROCAT to read stars from the astrometric CDROM Microcat
-
LONEOSMICROCAT to read Loneos stars from the CDROM Microcat.
-
TYCHOMICROCAT to read Tycho stars only from the astrometric CDROM Microcat.
-
USNO to read stars from the CDROM USNO (USNO A ou SA).
-
Data : orbital data. Values depends on the Format :
-
Format = INTERNAL : don't fill this element
-
Format = BOWELLFILE : full name of the file which contains orbital elements.
-
Format = MPCFILE : full name of the file which contains orbital elements.
-
Format = ASTROMMICROCAT : full name of the path to acces to the Microcat
catalog.
-
Format = LONEOSMICROCAT : full name of the path to acces to the Microcat
catalog.
-
Format = TYCHOMICROCAT : full name of the path to acces to the Microcat
catalog.
-
Format = USNO : full name of the path to acces to the Microcat catalog.
N.B. Words that defines Format and Data can be written uppercase or lowercase
without incidence.
For exemple, Jupiter planet is define by the following list
{jupiter internal}
or only by the word Jupiter since Internal is the default value. On
the other hand, for the asteroïd 1997DQ :
{1997DQ Bowellfile astorb.dat}
The type ListObjectss is a list of Objects or * for every objects defined
in the Data element. For exemple,
{ { {1} {6809} {10222} {1997DQ} } Mpcfile mpcorb.txt }
One another exemple, to define the nine planets of the solar system
plus the moon and the sun :
{ * Internal}
which can be written by only * because Internal is the default value
of Format.
2.1.4. Type Home
Type Home is used to locate a point on the Earth surface. By this way,
one can compute an topocentric ephemeris for that location (taking account
parallax effects). Type Home is defined by a list of the following elements
:
-
Format : to define the coordinate system employed. Choices are :
-
GPS : to define geographic coordinates longitude, latitude et altitude.
-
MPC : to define coordinates by longitude, rho cos(phi'), rho sin(phi')
-
MPCSTATION : to define coordinates from an IAU station number.
The other elements depend on the value of Format :
-
If Format = GPS, following elements are :
-
Longitude : floating point degrees. Positive value between 0 and 180.
-
Sens : E or W for the direction of the longitude from Greenwich.
-
Latitude : in degres. Positive for the northern hemisphere, négative
for the southern.
-
Altitude : in meters above the sea.
-
If Format = MPC, following elements are :
-
Longitude : floating point degrees. Positive towards East. Valeur between
0 and 360.
-
Rhocosphip : value of rho cos(phi').
-
Rhosinphip : value of rho sin(phi').
-
If Format = MPCSTATION, following elements are :
-
Numéro : IAU station number
-
Filename : name of the file that contains the IAU station numbers and their
locations.
N.B. Word that defines Format can be written uppercase or lowercase without
incidence.
For example, for the Paris observatory, located at 2.3375 degrees eastern
from Greenwich, rho*sin(phi') = 0.74918 and rho*cos(phi') = 0.65950, one
writes :
{ MPC 2.3375 0.65950 0.74918 }
Another example is given for an observatory located at 3 degrees western
from Greenwich, a latitude of 46 degrees and an altitude of 456 meters
:
{ GPS 3 W 46 456 }
2.1.5. Type Field
Type Home is used to define a field of view seen by an optic system which
produce a gnomonic projection (a CCD image for example). Type Field is
defined by a list of the following elements :
-
Format : to define prjection parameters. Values are :
-
BUFFER : to give projection parameters from a FITS image storaged in an
AudeLA buffer.
-
OPTIC : to give explicitly the projection parameters.
According to the value of format, the other elements are :
-
If Format = BUFFER, other elements are :
-
Numéro : The buffer number which contains the image.
-
If Format = OPTIC, other elements are:
-
NAXIS1 Value : number of points on the X axis.
-
NAXIS2 Value : number of points on the Y axis.
-
FOCLEN Value : focal length (in meters).
-
PIXSIZE1 Value : pixel size (in meters) on the X axis. Negative value if
the right ascensions increase when X decrease.
-
PIXSIZE2 Value : pixel size (in meters) on the Y axis. Negative value if
the declination increase when X decrease.
-
CROTA2 Value : position angle of North against the top of the image.
-
RA Value : right ascension J2000.0 of the center of the field.
-
DEC Value : declination J2000.0 of the center of the field.
N.B. Word that defines Format (NAXIS1, etc.) can be written uppercase or
lowercase without incidence.
For example, to define a field centered on 12h00m and 15d with a 2.5
meters focal length telescope, a 768x512 pixels of 9 microns size camera,
one writes :
{ OPTIC NAXIS1 768 NAXIS2 512 FOCLEN 2.5 PIXSIZE1 9e-6 PIXSIZE2 9e-6
CROTA2 0 RA 180 DEC 15 }
2.1.6. Types Format and ListFormat
Output format is a word which indicate the data to print. Values are :
-
RA : Right ascension (J2000.0) floating point degrees.
-
RAH : Right ascension (J2000.0) hour integer value
-
RAH.H : Right ascension (J2000.0) hour floating point value
-
RAM : Right ascension (J2000.0) minute time integer value
-
RAM.M : Right ascension (J2000.0) minute time floating point value
-
RAS : Right ascension (J2000.0) second time integer value
-
RAS.S : Right ascension (J2000.0) second time floating point value
-
DEC : Declination (J2000.0) floating point degrees
-
DECD : Declination (J2000.0) degrees, integer value.
-
DECM : Declination (J2000.0) minutes of degrees, integer value.
-
DECM.M : Declination (J2000.0) minutes of degrees, floating point value.
-
DECS : Declination (J2000.0) seconds of degrees, integer value.
-
DECS.S : Declination (J2000.0) seconds of degrees, floating point value.
-
OBJENAME : NAme of the object.
-
JD : Julian day.
-
YEAR : Year (integer)
-
MONTH : Month (integer)
-
DAY : Day (floating point).
-
MAG : Magnitude
-
DELTA : Distance to the Earth in U.A.
-
R : Distance Object-Sun in U.A.
-
ELONG : Elongation from the Sun
-
MOONELONG : angular distance from the Moon.
-
PHASE : Phase of the object.
-
APPDIAM : Apparent diamater in degrees.
-
AZIMUTH : Azinuth in degres (use the option -toto)
-
ALTITUDE : Altitude above the horizon in degres (use the option -toto)
-
HA : Hour angle in degres (use the option -topo)
N.B. Words that defines Format can be written uppercase or lowercase without
incidence.
Type ListFormat allows to write a list of parameters of type Format.
For example, to output the name, date and magnitude of an object, one writes
:
{ OBJENAME YEAR MONTH DAY MAG }
2.1.7. Type option -constraint
Type -constraint is dedicaced to options. It allows to exclude objects
out acceptable limits. Two syntaxes can be employed :
-
-contrainst> Value : to exclude every object which has a value lower than
the Value.
-
-contrainst< Value : to exclude every object which has a value upper
than the Value.
The following words can be used as constraints :
-
dec : for the declination
-
elong : for the Sun elongation
-
moonelong : for the elongation against the Moon.
-
delta : for an object-Earth distance.
-
r : for an object-Sun distance.
-
mag : for a magnitude
-
altitude : for an altitude above the horizon
-
azimuth : for an azimuth
-
ha : for an hour angle.
-
magr : for a R magnitude
-
magb : for a B magnitude
N.B. Words that defines Options and their arguments can be written uppercase
or lowercase without incidence.
Note : concerning options azimuth et ha, the meaning of > et < differs
slightly. -ha< 15 means to keep every object which have a hour angle
value lower than 15 degrees from the meridian. Same thing for azimuth.
For example, one wichs to keep only objects brighter than mag 12 but
fainter than mag 10, having declinations upper to -15 degres, an altutide
upper than 30 degrees. One writes :
-mag< 12 -mag> 10 -dec> -15 -altitude> 30
2.2. Tcl extension functions of MC
Here we explain how to use the MC functions in the Tcl interpreter.
2.2.1. Ephemeris
Le function which generates ephemeris is called mc_ephem.
mc_ephem ListObjects
?ListDates? ?ListFormat? -constraint
Value -topo Home
By default, ListDate=NOW and ListFormat={ OBJENAME RA DEC}
It returns a list. Each element contains data defined by ListFormat.
The last element of the list is different. It contains some informations
about the computation. Star catalogs are not taken into account. Options
-contrainst, magr and magb are not taken into account.
In the peculiar cases of objects of type asteroïds from the Bowell
ou MPC database, their are two extra options :
-
-numb 0 : to not compute numbered asteroïds.
-
-prov 0 : to not compute provisional designated asteroïds.
Examples :
-
mc_ephem *
Compute the geocentric position of the nine planets of the solar system,
plus the Sun and the Moon, for the present instant.
-
mc_ephem * {{2000 4 13}} {OBJENAME RAH RAM.M DECD
DECM.M}
Compute the geocentric position of the nine planets of the solar system,
plus the Sun and the Moon, for the 13th April 2000 at 0h UT. It returns
the following list :.
{Sun 1 26.500660 9 4.643786 } {Moon 8 59.144500 18 12.397345 } {Mercury
0 4.013105 -2 21.874075 } {Venus 0 30.576006 1 39.792178 } {Mars 2 51.951151
16 41.063033 } {Jupiter 2 39.101727 14 33.607830 } {Saturn 2 22.226011
12 0.620939 } {Uranus 21 30.867704 -15 25.648050 } {Neptune 20 34.942788
-18 27.282960 } {Pluto 16 50.524425 -11 2.882165 } {Ok {J2000.0 coordinates}
10}
-
mc_ephem {Sun Moon} {{1999 8 11 10 26} } -topo {GPS
2 E 48.5 125}
Compute the topocentric position of the Sun and the Moon, for the 11th
August 1999 at 10h26 UT. The location is defined by its geographic coordinates
(longitude 2 degrees eastern from Greenwich, latitude 48.5 degrees in the
northern hemisphere and an altitude of 125 meters). It returns the following
list :.
{Sun 140.762506 15.333362 } {Moon 140.784691 15.345038 } {Ok {J2000.0
coordinates} 2}
-
mc_ephem {* Bowellfile astorb.dat} now {OBJENAME RA
DEC MAG} -ha< 45 -dec> -15 -dec< 40 -mag< 17 -moonelong> 30 -topo
{MPCSTATION 148 stations.txt}
Compute the topocentric position, for the IAU station number
148, of every asteroïd from the Bowell database, brighter than magnitude
17, located at hour angles lower than 45 degrees from the meridan, between
declinations -14 and +40 degrees, and with an elongation upper than 30
degrees from the Moon.
In order to compute the ephemeris of an object for many dates, it is usefull
to generate the ListDates from the function mc_date2listdates.
2.2.2. Objects in a field
mc_readcat returns a list of objects in the field of a CCD image. Its syntax
is :
mc_readcat Field ListObjects
Output -constraint Value -objmax Value -date
Date -topo Home
The mandatory parameter Output indicates how to print the output datas
: a Tcl list or a file :
-
{FILE Filename} : That list of two elements begins with the word FILE and
the second word is the fille name of the texte file for the output datas.
-
LIST : To obtain output datas in a returned Tcl list.
The option -objmax allow to limit the number of objects in the output datas.
By defualt, its value is 1000.
The only options -contrainst, magb are magv can be used.
Option -date allows to define a date for the case of computation of
planetary positions (NOW by default).
Option -topo allows to define an Earth location for the case of computation
of planetary positions (geocentric by default).
The output format is : {RA DEC MAGB MAGR X Y OBJENAME}. Le field OBJENAME
is written only for planets. The last element of the list differ from the
others. It contains some informations about the computation.
Examples :
-
mc_readcat { OPTIC NAXIS1 768 NAXIS2 512 FOCLEN 2.5
PIXSIZE1 9e-6 PIXSIZE2 9e-6 CROTA2 0 RA 180 DEC 15 } {* TYCHOMICROCAT f:\\}
{LIST}
Compute the projection of every Tycho stars that are in the field defined
by the FITS keywords.
-
mc_readcat { BUFFER 1 } {* BOWELLFILE astorb.dat}
{LIST} -magb< 18 -magr< 18
Compute the projection of every asteroïds, from the Bowell database,
that are in the field defined by the FITS keywords of the buffer 1 image.
Only asteroïds brighter than magnitude 18 are outputed.
2.2.3. Angle convertions
mc_angle2deg Angle : returns angle formatted
floating point degrees.
mc_angle2rad Angle : returns angle formatted
floating point radians.
mc_angle2dms Angle ?dec?: returns angle
formatted as a list Dd Mm Ss.sss. If the second parameter is DEC, the result
is written between -90 to +90 degrees (else between 0 and 360 degrees).
mc_angle2hms Angle : returns angle formatted
as a list Hh Mm Ss.sss. The result is between 0 and 24 hours.
mc_angle2lx200dec Angle : returns angle
formatted as a string for the function Sd of the LX200 protocol.
mc_angle2lx200ra Angle : returns angle
formatted as a string for the function Sr of the LX200 protocol.
mc_anglesep ListAngles ?Units?: Returns
angle distance and the position angle. ListAngles is composed by 4 angles
on the following order : Ra1 Dec1 Ra2 Dec2. The result is expressed in
degrees by default. It can be expressed in redian if Unit=Radian.
Following function are obsolecents but can be used :
mc_deg2dms Degrees : Returns a list Dd Mm Ss.sss
mc_deg2hms Degrees : Returns a list Hh Mm Ss.sss
mc_dms2deg Dd Mm Ss.sss : Returns a list Degrees
mc_hms2deg Hh Mm Ss.sss : Returns a list Degrees
mc_sepangle Ra1 Dec1 Ra2 Dec2 ?Units? : returns angle distance
and the position angle. Ra1 Dec1 Ra2 Dec2 are expressed in floating point
degrees only. The result is expressed in degrees by default. It can be
expressed in redian if Unit=Radian.
2.2.4. Date conversions
mc_date2jd Date : returns the julian day from
a type Date.
mc_date2ymdhms Date : returns the gregorian
calendar date (Yyyy Mm Dd Hh Mm Ss.sss) from a type Date
mc_date2lst Date Home
: returns the local sideral time formatted Hh Mm Ss.sss from paraeter type
Date and Home.
mc_date2listdates Date
DateStep NbSteps : returns a list of ListDates from an initial Date increased
NbSteps times the step DateStep (in days).
Examples :
-
mc_date2ymdhms now
Returns a list formatted as year, month, day, hour, minute, second
:
2000 2 11 12 51 56.999991
-
mc_date2jd {2000 2 11 12 51 56.999991}
Returns the julian day :
2451586.036076
-
mc_date2lst now {gps 20 e 45 130}
Returns a list formatted hour, minute, second from the actaul time
and a location :
23 37 5.098954
-
mc_date2listdates now0 0.5 20
Returns a list of Dates (in julian days). The first element of the
returned list is the today date at 0h, and the following dates are increased
by a step of 0.5 days. One compute 20 dates by this way :
2451585.500000 2451586.000000 2451586.500000 2451587.000000 2451587.500000
2451588.000000 2451588.500000 2451589.000000 2451589.500000 2451590.000000
2451590.500000 2451591.000000 2451591.500000 2451592.000000 2451592.500000
2451593.000000 2451593.500000 2451594.000000 2451594.500000 2451595.000000
That list is usefull to compute an ephemeris (cf. function mc_ephem).
2.2.5. Astrometry
mc_buf2field Numbuffer : returns a ListField of optical parameters
from the header FITSQ of the image staraged in the buffer Numbuffer.
mc_xy2radec x y Field : returns a list
formatted {RA DEC}from the cartesian coordinates x et y.
mc_radec2xy ra dec Field : returns a list
formatted {X Y}from the coordinates ra and dec.
mc_listradec Field Mosaic ComPix : generate
a list of {X Y RA DEC} from a field of type Field, making a mosaïc
defined by the parameter Mosaic with an overlap of ComPix pixels between
each field. The mosaïc can be generated by different ways :
-
Mosaic = {FREE dx1 dy1 dx2 dy2 ...}: The first field is computed by a shift
of dx1,dy1 pixels from the field defined by Field. The second field is
computed by a shift of dx2,dy2 pixels from the first field (always refered
to the previous field). The ComPix parameters has no effect.
-
Mosaic = {NAXIS1 Nbfields} : The first field is defined by Field. The following
fields are shifted against the increased X axis if Nbfields is positive
(respectively against the decreased X axis if NbFields is negative). There
are NbFields field computed.
-
Mosaic = {NAXIS2 Nbfields} : The first field is defined by Field. The following
fields are shifted against the increased Y axis if Nbfields is positive
(respectively against the decreased Y axis if NbFields is negative). There
are NbFields field computed.
-
Mosaic = {ROLL Nbfields Parity} : The first field is defined by Field.
The following fields are shifted as a spiral around the Field. There will
be NbFields fields. The order of the fields is :
If Parity=0 then every fields will be computed (default value).
If Parity=1 then only the odd fields will be computed
If Parity=2 then only the even fields will be computed
-
Mosaic = {RANDOM Nbfields} : The first field is defined by Field.
The following fields are shifted randomly in a square of Compix pixels
by side centered on the Field position. There are NbFields field computed.
Examples :
-
mc_listradec {optic naxis1 256 naxis2 256 foclen 16
pixsize1 40e-6 pixsize2 40e-6 crota2 0 ra 95.345 dec 67.97} {roll 10} 15
Compute 10 fields that follow a spiral around the coordinates ra=95.345
degrees and dec 67.97=degrees. Field are overlapped by 15 pixels. Each
image will be taken by a 256x256 matrix with pixels of 40 microns size
and a focal length of 16 meters.
{95.345000 67.970000 128.000000 128.000000} {95.345000 68.004521 128.000000
369.000000} {95.252830 68.004495 369.000000 369.000000} {95.252967 67.969974
369.000000 128.000000} {95.253104 67.935454 369.000000 -113.000000} {95.345000
67.935479 128.000000 -113.000000} {95.436896 67.935454 -113.000000 -113.000000}
{95.437033 67.969974 -113.000000 128.000000} {95.437170 68.004495 -113.000000
369.000000} {95.437307 68.039016 -113.000000 610.000000}
Each element contains the right ascension (in degrees), the declination
(in degrees) and the x,y cartesian coordinates of the center of the field
in the coordinates system taken from the first field.
-
mc_xy2radec 13.45 115.78 {optic naxis1 256 naxis2
256 foclen 16 pixsize1 40e-6 pixsize2 40e-6 crota2 0 ra 95.345 dec 67.97}
Compute the ra,dec coordinates correponding to the cartesian coordinates
x=13.45 y=115.78 on an image defined by its optical parameters.
95.388741 67.968244
Coordinates ra,dec are expressed in degrees.