Miriade Ephemeris Generator
.: ephemph - PSV :.
Purpose
This method is intended to people who need to compute the apparent aspect - or physical ephemeris - of Solar system objects.
HTTP Request
The Miriade
ephemph service can be accessed using the
Miriade query forms.
If you are a software/solutions developer, you might want to include the Miriade
ephemph service into
your application. This can be done by using the
web service method or by using the following HTTP request:
- http://vo.imcce.fr/webservices/miriade/ephemph_query.php?[parameters]
where
[parameters] is a list of parameters separated by the character &.
The allowed parameters are:
Parameter | Definition | Limits or value |
-name=<string> |
The designation of the target (1) |
Ex.: p:Mars, p:5, s:io, a:Pallas, a:1999_TC36, c:p/halley |
-type=<string> |
Optional parameter to define the type of the target |
Asteroid | Comet | Dwarf Planet | Planet | Satellite |
-ep=<string> |
Requested epoch, expressed in Julian day or formatted as any English textual datetime (2) |
2086308.0 .. 2816788.0 1000-01-01 12h .. 3000-01-01 12h |
-nbd=<int> |
Number of date of ephemerides to compute [Optional parameter, default = 1] |
1 ≤ nbd ≤ 5000 |
-step=<string> |
Step of increment (float) followed by one of (d)ays or (h)ours or (m)inutes or (s)econds [Optional parameter, default = 1d] |
Ex.: 2.345h or 1d |
-tscale=<string> |
Ephemeris time scale [Optional parameter, default = UTC] |
UTC | TT |
-so=<int> |
Physical model number (3) [Optional parameter, default = 1] |
1 ≤ so ≤ 99 |
-observer=<string> |
Code of the observer location (4) [Optional parameter, default = 500] |
Ex.: 500 (geocenter), 007 (Paris) |
-mime=<string> |
Mime type of the results |
votable | html | text | image |
-view=<string> |
Output format of the images (5) [Optional parameter, default = none] |
[wired:]eps|png | psv[:fits|png] | none |
-rv=<int> |
Compute radial velocity or not [Optional parameter, default = 0] |
0 | 1 |
-anim=<int> |
Mode animate: draw an image for each date, else draw an image only for the first date [Optional parameter, default = 0] |
0 | 1 |
-print=<int> |
Display ephemeris date results or not [Optional parameter, default = 0] |
0 | 1 |
-visu=<string> |
Comma separated list of options to pass to the image generator (PSV) (6) [Optional parameter, default = blank] |
|
-output=<string> |
Comma separated list of options to format the output of the ephemeris (7) [Optional parameter, default = blank] |
|
-from=<string> |
Word which definite the name of the caller application, or which describes the request |
any short string (without space) |
- See the HOWTO section for a full description about how to name targets.
- See the HOWTO section to known how to define the computation epoch.
- The physical model number can be obtained through the dedicated GET API of Miriade.ephemph.
- The observer location can be defined by its IAU
code or a particular code. See HOWTO section.
- See the HOWTO section for a description of the generated images.
- See the HOWTO section for a description of the syntax to pass arguments
to the PSV image generator.
- See the Optional parameters section to know how to add extra ephemeris data,
and the Output parameters section for a description of the outputs.
The output parameters are described in the following table and are available in
VOTable (default), HTML or plain text format
(cf. examples). Some parameters are optionnal, and their values can be
omitted (just left blank the value, e.g. &-mime=&-visu=). The other inputs are mandatory.
HTTP Request specific interface
This interface must only be used to request the list of physical models available for the computation of the physical ephemerides of
solar system objects in Miriade.ephemph. This is done by using the following HTTP request:
- http://vo.imcce.fr/webservices/miriade/ephemph_query.php?-get=<keyword>[&-name=<target>&-mime=<mime>]
where:
Parameter | Definition | Limits or value |
-get=<keyword> |
keyword = model | models
|
model |
-name=<string> |
The designation of the solar system objects: <prefix>:<name> Leave
the name part empty to get the physical models of all objects of type <prefix>, e.g.
-name=p: retrieves all the physical models of planets.
Provide the name of a given object to get its physical models.
|
Ex.: a:pallas, a:Kalliope, p: |
-mime=<string> |
Mime type of the results, optional, default text/csv |
json | text/csv | text | votable | html |
-from=<string> |
Word which definite the name of the caller application, or which describes the request |
any short string (without space) |
Examples: click on the following links to get:
The query returns a document, formatted according
to the given MIME type, containing the following information:
Parameter | Definition | Unit or Value |
ssotype | Type of the target | Asteroid | Planet | Satellite | Comet |
ssonum | Official number of the target (blank if unknown) | |
ssoname | Name or designation of the target | |
ssomodel | Name of the physical model | EPROC | DAMIT |
ssomodelid | Id of the physical model | 1..99 |
iauspin_ra | Right ascension of the spin axis | deg |
iauspin_dec | Declination of the spin axis | deg |
iauspin_w | Longitude of the prime meridian | deg |
iauspin_wp | Rotation rate | deg/d |
iauspin_tref | Reference epoch of the prime meridian longitude | julian day |
ssospinfile | Existence of spin data according DAMIT database | yes | no |
ssoshapefile | Existence of shape model according DAMIT database | yes | no |
ssoringfile | Existence of ring definition | yes | no |
ssofeaturefile | Existence of features on the surface of the target | yes | no |
To query the physical ephemerides of a solar system object with a specific physical model,
use the given ID as the value of the
-so argument.
Web service
The Miriade Web service provides methods based on
SOAP and
HTTP POST verb which allow
one to interact between its own application and the Miriade service. Here is the useful information to
invoke the Miriade
ephemph method:
- Web Service URI:
- http://vo.imcce.fr/webservices/miriade/miriade.php
- Namespace:
- http://vo.imcce.fr/webservices/miriade
- WSDL:
- http://vo.imcce.fr/webservices/miriade/miriade.php?wsdl
- SOAP header:
- name of the SOAP header element: 'clientID'
- SOAP header's content: array('from' => 'YourName', 'hostip'=>'', 'lang'=>'en|fr')
- Method:
- ephemph (inputArray)
The input parameters of the method is an array which must
contained the following parameters:
Variable | Type | Units | Limits or values | Default | Comment |
name |
string |
- |
- |
none |
Name or number of the target (1) |
type |
string |
- |
Asteroid | Comet | Dwarf Planet | Planet | Satellite |
none |
Type of the target |
epoch |
string |
epoch or URL |
2086308.0 .. 2816788.0 1000-01-01 12h .. 3000-01-01 12h |
none |
Requested epoch (julian day, ISO format, English textual datetime), or list of epochs provided through an URL (2) |
nbd |
int |
- |
1 ≤ nbd ≤ 5000 |
1 |
Number of date of ephemerides to compute |
step |
string |
d|h|m|s |
step ≤ 500d |
1d |
Step of increment (float) followed by one of (d)ays or (h)ours or (m)inutes or (s)econds |
tscale |
string |
- |
UTC | TT |
UTC |
Time scale of the ephemeris |
so |
int |
- |
1 ≤ so ≤ 99 |
1 |
ID of the physical model to use (3) |
observer |
string |
- |
IAU observatory or particular code |
500 |
IAU code of the observer location (4) |
mime |
string |
- |
votable | html | text | image |
votable |
Mime type of the results |
view |
string |
- |
[wired:]eps|png | psv[:fits|png] | none |
none |
Output format of images (5) |
rv |
int |
- |
0 | 1 |
0 |
Compute radial velocity or not |
anim |
int |
- |
0 | 1 |
0 |
Mode animate: draw an image for each date, else draw an image only for the first date |
print |
int |
- |
0 | 1 |
0 |
Display ephemeris results or not |
visu |
string |
- |
Inactive |
blank |
Comma separated list of options to pass to the image generator (PSV) (6) |
output |
string |
- |
- |
blank |
Comma separated list of options (7) |
- See the HOWTO section for a full description about how to name targets.
- See the HOWTO section to known how to define the computation epoch.
- The physical models of objects can be gathered through the dedicated Miriade.ephemph GET API.
- See the HOWTO section to know how to define the observer location.
- See the HOWTO section for a description of the generated images.
- See the HOWTO section for a description of the syntax to pass arguments to the PSV image generator.
- See the Optional parameters section to know how to add extra ephemeris data,
and the Output parameters section for a description of the outputs.
The output parameters of the method is an object containing
the following attributes:
- 'flag'
- the status of the response: flag=1 means ok; flag=0 or flag=-1 mean that an error occured
- 'ticket'
- the Unix timestamp of the answer which can be useful to stamp the request
- 'result'
- a string containing the ephemeris of the requested solar system body (cf. Output parameters section).
Depending on the selected mime type, the output is formatted as:
- votable
- the data are written in the IVOA standard VOTable format
- html
- the data are transformed in a HTML document using a XSLT processing (Miriade XSL style sheet)
- text
- the data are returned in plain text where each block of data is separated by the semi-colon character ;.
The block of data starts with the keyword #! ephem (if print=1 then it is the first block). The lines
which contain the URL to download the generated images start with the keyword #! image <idx>
where <idx> starts at 0 and ends at nbd-1.
- image
- the first image only is returned, whatever the choosen number of dates and the value of the argument -anim.
Examples: click on the following links to get the
geocentric physical ephemeris of asteroid Kleopatra for epoch=2453002.24128009239, nbd=5, step=1d, so=1,
observer=500, rv=0, print=1, output=--iso, and:
- mime=text, view=none, anim=0 (data only)
- mime=html, view=wired:png, anim=1 (data & images)
- mime=html, view=psv:png, anim=1 (data & images)
- mime=votable, view=wired:png, anim=1 (data & images)
- mime=image, view=wired:png, anim=0 (image only)
Optional parameters:
The optional parameters (-output) can be used to format the display of the date:
-
--greg
-
format the epoch as a calendar date.
-
--iso
-
format the epoch as an ISO-8601 date (default)
-
--julian
-
format the epoch as a julian day.
or to add extra ephemeris data:
-
--coord:eq
-
add the spherical equatorial coordinates of the target (RA, DEC), apparent frame (true equator, equinox of the date)
-
--coord:eq2000
-
add the spherical equatorial coordinates of the target (RA, DEC), mean J2000 frame (mean equator, mean equinox)
-
--coord:ec
-
add the spherical ecliptic coordinates of the target (λ, β), apparent frame (true equator, equinox of the date)
-
--coord:rect
-
add the rectangular equatorial coordinates of the target (x,y,z), apparent frame (true equator, equinox of the date)
Output parameters:
The following table shows the output parameters of the
ephemph method.
Col. |
Definition |
Units |
Format |
Label |
1 |
Gregorian Date |
datetime |
default to ISO-8601 |
Date UTC |
2,3 |
Sub-Earth point longitude and latitude (1) |
degree |
decimal |
SEP |
4,5 |
Sub-Solar point longitude and latitude (2) |
degree |
decimal |
SSP |
6 |
North pole position angle w.r.t. celestial north pole |
degree |
decimal |
PA_n |
7 |
Angular distance between the pole and the center of the body |
arcsec |
decimal |
d_p |
8 |
Visual magnitude |
- |
decimal |
Mv |
9 |
Phase angle |
degree |
decimal |
i |
10 |
Body angular radius |
arcsec |
decimal |
R_app |
11 |
Range to observer |
AU |
decimal |
Dg |
12 |
Heliocentric distance |
AU |
decimal |
Dh |
13 |
Angle of position of the equator of intensity |
degree |
decimal |
PA |
14 |
Length of the right-side segment on the equator of intensity which is not illuminated
(on the surface of the apparent disc of planet) |
arcsec |
decimal |
Q |
15,16 [,17] |
Coordinates of the target expressed in spherical or rectangular format in the chosen reference frame (true or mean) |
hms | dms au |
sexagesimal decimal |
RA,DEC | LON,LAT x,y,z |
- In the case of the Moon, the selenocentric coordinates of the Earth take account of the lunar
surface periodic oscillations or (optics and physics) librations, which allow to discover up to
59% of its surface seen from the Earth.
- In the case of the Moon, we provide the colongitude of the Sun, defined as the East selenocentric
longitude of the terminator. Colongitudes 270°, 180°, 90° and 0° correspond, at a
few nearest hours, to new moon, first quarter, full moon and last quarter.
Graphical output:
When the argument
view is not none, the physical ephemerides are completed
by figures, which show graphically the apparent aspect of the target at each epoch.
Two graphic modes are available:
- - wired style
- view=[wired:]png|eps : the target is modeled with an ellipsoid of revolution (grid 5°x5°)
projected on the sky plane.
The red and yellow marks show respectively the sub-earth and sub-solar points, the cyan great
circle materializes the prime meridian, and the grey zone enlights the solar phase.
Example: planet
Saturn now.
- - 3D shape model
- view=psv[:fits|png] : the target is modeled with a 3D shape model, finely rendered with our
Planetary Scene Viewer software.
This mode is experimental for now. The code is liable to evolve in the coming months.
Example: asteroid
Pallas now.
How to consume:
You have two ways to use the Miriade web service: by writting a client to send requests to the Miriade server and
to receive and analyze the response, or by using a command line interface and a data transfert program such as
curl or
wget. For that, just
execute one of the following commands in a console:
#> curl "<URL>"
or
#> wget "<URL>"
where <URL> is described in section
HTTP request.
In order to help you to invoke the Miriade web service, we provide some clients
written in differents languages. Here are some detailed explanations to see how to write a client with PHP
and SOAP which invokes the ephemph method:
1/ Provide the input parameters which are mandatory for the service:
// Client's ID: provide the name of your project or organisation or yourself
$from = 'MyName';
// Input parameters
$param = array(
'name' => 'a:pallas',
'type' => '',
'epoch' => 2453002.24128009239,
'nbd' => 5,
'step' => '1h',
'tscale' => 'UTC',
'so' => 1,
'observer' => '500',
'mime' => 'text',
'view' => 'wired:png',
'rv' => 0,
'anim' => 1,
'print' => 1,
'visu' => '',
'output' => '--iso,--coord:eq'
);
2/ Define the SOAP options, the namespace and the WSDL URI of Miriade web service:
// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// SkyBoT namespace
$namespace = 'http://vo.imcce.fr/webservices/miriade';
// SkyBoT WSDL
$uriwsdl = $namespace.'/miriade.wsdl';
3/ Create a SoapClient object in WSDL mode, set the SOAP header, then call the method and catch exceptions:
try
{
// Constructs the client
$client = new SoapClient($uriwsdl, array('exceptions'=>1, 'soap_version'=>"SOAP_1_2"));
// SOAP header
$header = array('from'=>$from, 'hostip'=>'', 'lang'=>'en');
$client->__setSoapHeaders(array(new SOAPHeader($namespace, 'clientID', $header)));
// Call the resolver method
$response = $client->__soapCall('ephemph',array($param));
// Display the results
if (! empty($param['get'])) {
switch ($param['mime']) {
case 'text':
$contentType = "Content-Type: text/plain";
break;
case 'text/csv':
$contentType = "Content-Type: text/csv";
break;
case 'json':
$contentType = "Content-Type: application/json";
break;
case 'votable':
$contentType = "Content-Type: text/xml;content=x-votable";
break;
}
header("HTTP/1.0 ".$response->status);
header($contentType);
echo $response->result."\n";
} else {
// Affichage du resultat
if ($param['mime'] == 'text') {
$res = explode(';', $response->result);
$nbr = count($res);
$newkey = array_keys($res);
header("HTTP/1.0 ".$response->status);
header("Content-Type: text/plain");
echo "# Flag: ".$response->flag."\n";
echo "# Ticket: ".$response->ticket."\n";
for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]],"\n"; }
} else if ($param['mime'] == 'image') {
if ($response->flag == 1) {
switch ($param['view']) {
case "fits":
case "psv:fits":
$content = "image/fits";
break;
case "png":
case "psv:png":
case "wired:png":
$content = "image/png";
break;
case "eps":
case "wired:eps":
$content = "application/postscript";
break;
}
header("HTTP/1.0 ".$response->status);
header("Content-Type: ".$content);
echo file_get_contents($response->result);
} else {
header("HTTP/1.0 ".$response->status);
header("Content-Type: text/xml;content=x-votable");
echo $response->result."\n";
}
} else {
header("HTTP/1.0 ".$response->status);
header("Content-Type: text/xml;content=x-votable");
echo $response->result."\n";
}
}
}
catch (SoapFault $fault)
{
trigger_error("SOAP Fault: {$fault->getTraceAsString()} (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);
}