1. General points
| ^ |
---|
Miriade is a service of the IMCCE's Virtual Observatory project allowing the computation of
the ephemerides of the solar system objects (Sso):
- ephemcc: calculation of positional ephemeris
- ephemph: calculation of physical ephemeris
- rts: calculation of rise, transit and set
- vision: calculation of the visibility of Sso
The service can be used as a Web service and easily integrated into your own software (cf.
Miriade main page). We propose some examples of
client programs for that. The service can also
be used through a Web form which allows to choose
your input parameters, and to submit requests of ephemeris computation. This page describes
how to fill in some of the input parameters of the service.
|
|
2. How should I use Miriade to compute ephemerides of solar system objects?
| ^ |
---|
Several methods can be helpful:
- use the Miriade query forms available on the VO-IMCCE Web site
- implement yourself the Miriade Web service methods in your own software
(see client templates) or call the HTTP request on the
command line interface using non-interactive file transfert programs such as wget or curl
(see the how to consume paragraph of each Miriade method).
- use the Miriade services through a VO-compliant software which implements them, such as
Aladin and the Miriade plugin,
or the Astrogrid VODesktop
|
|
3. How to select a Sso by its name?
| ^ |
---|
The choice of a Sso can be done by its official name, or its number, or its provisional designation.
For the moment, the knowledge database of Miriade does not recognize all the possible designations of
Sso. In particular, historical names of asteroids, comets and natural satellites are not recognized.
You must use the current designations of Sso. The nomenclature of names of Sso is defined and
maintained by the Working Group for Planetary System Nomenclature
(WGPSN) of the Division III of
the International Astronomical Union.
The general syntaxe of Sso names in Miriade is the following:
- <prefix>:<name>[/X]
where <prefix> is one of the following codes:
- a to point out an asteroid
- c to point out a comet
- dp to point out a dwarf planet
- p to point out a planet
- s to point out a natural satellite
and where <name> is the official number or name, or the provisional
designation of the Sso. The space character in the provisional designation of asteroids can be substituted
by the underscore ('_') or the HTML character '%20'.
If no prefix is used, the type of the Sso must be provided through the
type argument. The list of known types is:
- Asteroid
- Comet
- Dwarf planet
- Planet
- Satellite
The old nomenclature (aster, comet, planet, satel) is still usable.
Restriction: the names of asteroids and comets must be the ones adopted in
ASTORB and COMETPRO databases. If not, they could not be recognized. For the natural satellites,
only the ones for which an ephemeris is available are recognized.
Binary asteroids:
If the name of an asteroid is suffixed by /X then the differential position
of its satellite (if it exists) is also computed. X is an integer, varying
from 1 to n, where n is the rank number of the orbital solution of the satellite.
Example: a:kalliope/1 allows to compute the ephemerides of the asteroid (22)
Kalliope and its satellite Linus. The list of orbital solutions available for satellites of binary
asteroids can be obtained through the Miriade.ephemcc method and its dedicated interface.
Examples:
|
|
4. How to request ephemerides of a list of Sso?
| ^ |
---|
To request ephemerides of multiple Sso in a single request, you have to provide a
text file (Content-Type: text/plain) containing a comma separated list of Sso designations
(multi lines accepted).
Example of file:
1,2,3
4,5,6
There are two ways to submit the file of targets:
- HTTP request: use 'curl' to POST the file when submitting the
request. Prefix the file name with an @ sign to force the content part to be a file (c.f. curl manual),
and use the key 'targets' to introduce the file name. Example:
curl -F "targets=@<filename>" "http://vo.imcce.fr/webservices/miriade/ephemcc_query.php?<args>"
where <filename> is the name of the local file which contains the targets. In that case,
the parameter -name must be omitted in the arguments, and the -type parameter MUST be use to specify
the type of solar system objects (e.g. aster | planet | satel | comet).
- SOAP client: you have to store your file on a Web server, and to provide a valid URL into the
name parameter of the ephemcc method, so that the Miriade server can get the file content.
Use the type parameter to specify the type of solar system objects (e.g. aster | planet | satel | comet).
Example (php client):
// Input parameters
$param = array(
'name' => 'http://my.webserver/~joe/targets.dat',
'type' => "aster",
... other args ... );
Restriction: A file must contain only one type of solar system objects: planets and natural satellites or asteroids or comets).
A file must contain not more than 5000 targets.
|
|
5. How to define the computation epoch?
| ^ |
---|
The epoch must be formatted as a textual english date (in accordance with the
GNU syntax of dates),
or as a julian day or as an ISO 8601 date.
Examples (non exhaustive) of valid dates:
- now
- 2006-01-27T1:53:34
- 2453762.529467592
- 10 September 2000
- +1 day
- +1 week 2 days 4 hours 2 seconds
- next Thursday
- last Monday
The timescale of the epoch is given by the option -tscale. The time span of
ephemeris covers the period 1000-01-01 12h to 3000-01-01 12h for the planetary theory INPOP, and
1599-12-09 0h to 2200-02-01 0h for the planetary theory DE405 (option -theory).
Restriction: the Miriade Web service accepts only julian day as valid input. The seconds must
be an integer number in the ISO format. For a time resolution better than a second, please use the
julian day.
Tolerance: le character 'T' of the ISO 8601 format can be omitted.
|
|
6. How to request ephemerides for a list of epochs?
| ^ |
---|
In order to request the ephemerides of Sso for multiple epochs, you have to provide a
text file (Content-Type: text/plain) containing a list of epochs (one per line). The epochs can
be formatted as a textual english date (in accordance with the
GNU syntax of dates),
as a julian day or as an ISO 8601 date. Different formats can be mixed in the same file.
Example of file (one date per line):
2456246.535046296
2456247.835046296
2456248.135046296
now
2012-11-17T12:36:12.1
2012-11-17T12:46:42.123
2012-11-17T13:26:2.15
There are two ways to submit the file of epochs:
- HTTP request: use 'curl' to POST the file when submitting the
request. Prefix the file name with an @ sign to force the content part to be a file, and use the key
'epochs' to introduce the file name. Example:
curl -F "epochs=@<filename>" "http://vo.imcce.fr/webservices/miriade/ephemcc_query.php?<args>"
where <filename> is the name of the local file which contains the epochs. In that case,
the parameters -ep, -nbd and -step must be omitted in the arguments.
- SOAP client: you have to store your file on a Web server, and to provide a valid URL into the
epoch parameter of the ephemcc method, so that the Miriade server can get the file content.
The nbd and step parameters can not be filled. Example (php client):
// Input parameters
$param = array(
'name' => 'a:Ceres',
'type' => "",
'epoch' => "http://my.webserver/~joe/epochs.dat"
'nbd' => "",
'step' => "",
... other args ... );
Restriction: A file must contain not more than 1000 epochs.
Recommendation: Ascending sort order of epochs optimizes the ephemeris computation.
|
|
7. How to define the coordinates of an observer?
| ^ |
---|
For a terrestrial observer, enter the IAU code
of the observatory of your choice, or the code 500 for an observed located at the centre of mass of the Earth (geocenter).
If the place of observation is not referenced in the database of IAU observatory, then provide the geographical
coordinates formatted as: [+-]longitude [+-]latitude altitude. The longitude and latitude must be expressed in
decimal degrees, and the altitude in meters. Longitudes are negative toward East. The sign + of the longitude and
latitude can be omitted. If not, use the encoding %2B instead of the symbol + (which is not correctly transmitted in URL).
Example: -observer=-2.23124 %2B48.45125 250.0
For an extra-terrestrial observer, use one of the following codes recognized by Miriade:
- @0 | 500@0
- for an observer located at the barycenter of the Solar System
- @sun | sun
- for an observer located at the center of mass of the Sun
- earth@L2 | 500@L2 | L2
- for an observer located at the libration point L2 of the system Sun-(Earth+Moon)
- venus@L2
- for an observer located at the libration point L2 of the system Sun-Venus
- mars@L2
- for an observer located at the libration point L2 of the system Sun-Mars
- jupiter@L2
- for an observer located at the libration point L2 of the system Sun-Jupiter
- saturn@L2
- for an observer located at the libration point L2 of the system Sun-Saturn
- mars | 500@mars
- for an observer located at the centre of mass of Mars
- spirit | @-254
- for an observer located at the landing site of the Spirit rover,
the first Nasa's Mars Exploration Rover.
The areocentric coordinates of this site are λ=175.4729°E ; φ=14.5692°S in the
IAU 2000 frame (Arvidson et al., Science vol. 305, 2004).
- opportunity | @-253
- for an observer located at the landing site of the Opportunity rover,
the second Nasa's Mars Exploration Rover.
The areocentric coordinates of this site are λ=354.47°E ; φ=1.95°S in the
IAU 2000 frame (MER factsheet).
For an observer onboard a spacecraft, use one of the following codes recognized by Miriade (period of validity in UTC):
- cassini | @-82
- for an observer located onboard the Cassini spacecraft. Period of validity of the orbit: 2001-03-07T12:00:00 -- 2006-10-19T12:00:00
- galileo | @-77
- for an observer located onboard Galileo spacecraft. Period of validity of the orbit: 1995-11-20T23:58:59 -- 2002-11-26T07:58:55
- hst | @-48
- for an observer located onboard the Hubble Space Telescope (HST). Period of validity of the orbit: 1990-04-25T02:00:00 -- 2015-07-30T02:18:00
- iso
- for an observer located onboard the ISO satellite. Period of validity of the orbit: 1995-11-17T12:36:36 -- 1999-01-01T13:52:00
- iss | @-125544
- for an observer located onboard the International Space Station (ISS). Period of validity of the orbit: 2008-02-08T13:00:00 -- 2009-01-26T13:00:00
- juno | @-61
- for an observer located onboard Juno spacecraft. Period of validity of the orbit: 2011-08-05T17:18:06 -- 2018-02-21T11:39:42
- kepler | @-227
- for an observer located onboard the Kepler spacecraft. Period of validity of the orbit: 2009-03-07T06:22:56 -- 2018-12-31T23:58:50
- rosetta | @-226
- for an observer located onboard the Rosetta spacecraft. Period of validity of the orbit: 2004-03-02T09:25:18 -- 2014-08-04T01:15:00
- sirtf | sst | @-79
- for an observer located onboard the Sptizer Space Telescope (SST ou SIRTF). Period of validity of the orbit: 2003-08-25T06:26:00 -- 2017-01-01T00:03:50
- voyager1 | @-31
- for an observer located onboard the Voyager 1 spacecraft. Period of validity of the orbit: 1977-09-08T09:08:17 -- 1979-01-14T15:51:00 ;
1979-04-24T07:33:03 -- 1980-10-06T10:14:10 ;
1980-12-20T16:45:20 -- 2021-01-01T00:00:00
- voyager2 | @-32
- for an observer located onboard the Voyager 2 spacecraft. Period of validity of the orbit: 1977-08-23T11:29:11 -- 1979-05-03T21:42:56 ;
1979-09-15T11:07:26 -- 1981-07-04T11:59:00 ;
1981-10-17T18:43:57 -- 1986-01-04T11:58:00 ;
1986-02-14T00:01:31 -- 1989-08-02T10:57:30 ;
1989-09-16T20:56:58 -- 2021-01-05T00:00:00
- xmm-newton | @-10
- for an observer located onboard the XMM-NEWTON spacecraft. Period of validity of the orbit: 1999 DEC 16 11:28:00 -- 2016 AUG 09 13:59:41
Sources of kernels:
- Cassini: http://naif.jpl.nasa.gov/pub/naif/pds/data/co-s_j_e_v-spice-6-v1.0
- ISO: http://iso.esac.esa.int/manuals/HANDBOOK/gen_hb/
- ISS: NASA, provided by the BUSOC
- HST: ftp://naif.jpl.nasa.gov/pub/naif/HST/kernels/
- Kepler: http://archive.stsci.edu/missions/k2/spice
- Rosetta: ftp://ssols01.esac.esa.int/pub/data/SPICE/ROSETTA/kernels/
- SIRTF: ftp://naif.jpl.nasa.gov/pub/naif/SIRTF/kernels/
- Voyager 1,2: ftp://naif.jpl.nasa.gov/pub/naif/VOYAGER
- Juno: http://naif.jpl.nasa.gov/pub/naif/JUNO/kernels/
|
|
8. How to define celestial objects in ViSiON service?
| ^ |
---|
The choice of a Solar system object (Sso) can be done by its official name, or its number, or its provisional designation.
For the moment, the knowledge database of Miriade does not recognize all the possible designations of Sso. In particular,
historical names of asteroids, comets and natural satellites may not be recognized. To avoid that, we recommend to use the
current designations of Sso. The nomenclature of names of Sso is defined and maintained by the
Working Group for Planetary System Nomenclature (WGPSN) of the
Division III of the
International Astronomical Union.
The choice of a (extra)galactic object must be done by an identifier recognized by the Simbad
astronomical database, maintained by the Strasbourg astronomical Data Center.
The general syntaxe of celestial object names in Miriade.ViSiON is the following:
- <prefix>:<nom>[=alias]
where <prefix> is one of the following codes:
- ' a ' to point out an asteroid
- ' c ' to point out a comet
- ' dp ' to point out a dwarf planet
- ' e ' to point out any fixed point on the celestial sphere
- ' p ' to point out a planet or a natural satellite
- ' u ' to point out a Simbad object
where <name> is the official number or name or the provisional designation of a Sso,
or an identifier recognized by Simbad astronomical database for non Sso,
or the equatorial coordinates of any fixed point on the celestial sphere.
where <alias> is the name that will be associated to the object in tables and figures
of ViSiON (e.g. u:TYC_5595009821=PSF1).
Restrictions:
- the names of asteroids and comets must be the ones adopted in ASTORB and COMETPRO databases. For the natural satellites,
only the ones for which an ephemeris is available are recognized.
- the names of celestial objects outside the solar system must comply with the
Dictionary of Nomenclature of celestial objects of Simbad.
The syntaxe of the names must follow the following rule:
- <catalogue>_<identifier> | <proper_name>
where catalogue is the acronym of the catalogue (e.g., HIP, TYC, ...),
where identifier is the identifier of the object (usually a number). If the numer is composed
of a sequence of numbers (e.g. FFFF-NNNNN-N) then the leading zero must be discarded, e.g. TYC 5595-00982-1 is written TYC_55959821,
where proper_name is the usual name of the object (e.g. Polaris, Sirius).
Examples: M_31, HIP_11767, Polaris, TYC_55959821
- the fixed points on the celestial sphere are defined by their equatorial coordinates (RA,DEC), and must comply the format:
- <RA>±<DEC>
with RA and DEC expressed in hours and degrees, formated in decimal or sexagesimal number (with the character '_' as
field separator). It is recommended to encode the '+' sign of DEC by its term percent-encoding '%2B'.
Examples: e:0_10_30%2B45_2_12.4, e:0.175-45.03678
|
|
9. How can I change the criteria for visibility in ViSiON service?
| ^ |
---|
The criteria of visibility can be tuned by defining values or range of values for multiple parameters specifying the required
conditions of for observation. The criteria are provided through the cuts parameter of the Web service, or by using
the "Advanced parameters" item of the ViSiON query form. In both cases, they are defined by a coma
separated list of tags written as an IDL structure:
- <tag1>:<value1>, ..., <tagN>:<valueN>
The list of accepted tags is:
- el:{min:<minval>,max:<maxval>}
- Minimum and maximum elevation of the target, in degrees
- mag:{min:<minval>,max:<maxval>}
- Minimum and maximum apparent V magnitude of the target
- phase:{min:<minval>,max:<maxval>}
- Minimum and maximum solar phase angle, in degrees, for solar system objects only
- elong:{sun:<val>,moon:<val>}
- Minimum solar and lunar elongation, in degrees
- diam:{min:<minval>,max:<maxval>,unit:<val>}
- Minimum and maximum apparent diameter of the target, in the specified unit (sec, min, deg)
- duration:<val>
- Minimum time span during which all conditions are met, in minutes
- event:'<val>'
- Event defining the beginning and the end of the night, either sunrise/sunset: <val>=sun,
or the civil, nautical, or astronomical twilights: <val>=civil|nautic|astro
Examples:
- Set minimum elevation to 40°: el:{min:40.0}
- Set elevation between 60° and 80°: el:{min:60.0,max:80.0}
- Set maximum phase angle to 20°: phase:{max:20.0}
- Set minimum time span during which conditions are met to 1h: duration:60.0
- Set night begin/end to astronomical twilight: event:'astro'
All tags are optional. The default criteria of visibility are:
- Elevation = 30° to 90 °
- Magnitude = -30 to 90
- Phase = 0° to 180°
- Sun elongation = 30°
- Moon elongation = 5°
- Diameter = 0.0 to 9999.0 arcsec
- Duration = 10 minutes
- Night limits = 'civil'
|
|
10. How can I change the order in which the targets are listed in ViSiON service?
| ^ |
---|
The order in which ViSiON lists the targets can be set via the simple sort parameter of the Web service, or by using the
"Advanced parameters" item of the ViSiON query form. The sort parameter can take the following values:
- mv
- Sort by apparent magnitude
- diam
- Sort by apparent diameter
- RA
- Sort by right ascencion [default]
- Dec
- Sort by declination
- rate
- Sort on non-sidereal rate
- alt
- Sort by the maximum altitude reached
- az
- Sort by the azimuth at maximum altitude
- gLon
- Sort by galatic longitude
- gLat
- Sort by galatic latitude
- dObs
- Sort by the range to observer
- dSun
- Sort by heliocentric distance
- phase
- Sort by phase angle
- sunE
- Sort by solar elongation
- moonE
- Sort by lunar elongation
- type
- Sort by target type (asteroid, planet, star...)
When sorting by target type, a second sorting parameter can be set,
among the list above, with the following syntax: type>parameter.
|
|
11. How is designed the JSON object provided by Miriade.ephemcc
| ^ |
---|
The ephemerides are encapsulated into a JSON object defined as follow:
{ "sso": {}, "coosys": {}, "ephemeris": {}, "data": {}, "unit": {} }
where sso provides information about the celestial object:
"sso": { "num": int,
"name": string,
"type": string,
"parameters": {
"diameter": float,
"ceu": float,
"ceurate": float,
"orbital_period": float,
"mass": float,
"dynamical_class": string,
"taxonomy": { "class": string, "param": string, "source": string } }
where coosys provides information about the celestial reference frame:
"coosys": { "epoch": string, "equinox": string, "system": string }
where ephemeris provides information about the ephemeris computation:
"ephemeris": { "time_scale": string,
"planetary_theory": string,
"relativistic_perturbations": string,
"coordinates": string,
"reference_frame": { "type": string, "plane": string, "center": string } }
where data contains the ephemeris of the body:
"data": [ { "epoch": float,
"ra": float,
"dec": float,
"dobs": float,
"vmag": float,
"phase": float,
"solar_elongation": float,
"mu_ra_cosdec": float,
"mu_dec": float,
"dobs_dot": float } ]
and where unit provides the unit of the quantities:
"unit": { "<keyword>": string [, "": string, ...] }
where keyword belongs to the list of the keywords used inside
the document.
|
|