Logo IMCCE-VOParis

THE IMCCE VIRTUAL OBSERVATORY
SOLAR SYSTEM PORTAL
Observatoire de Paris / CNRS

Logo IMCCE
Portal Home Page | Report issue | Legal notice | Contact us

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:
ParameterDefinitionLimits 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)
  1. See the HOWTO section for a full description about how to name targets.
  2. See the HOWTO section to known how to define the computation epoch.
  3. The physical model number can be obtained through the dedicated GET API of Miriade.ephemph.
  4. The observer location can be defined by its IAU code or a particular code. See HOWTO section.
  5. See the HOWTO section for a description of the generated images.
  6. See the HOWTO section for a description of the syntax to pass arguments to the PSV image generator.
  7. 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:
ParameterDefinitionLimits 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:

ParameterDefinitionUnit or Value
ssotype Type of the targetAsteroid | Planet | Satellite | Comet
ssonum Official number of the target (blank if unknown)
ssoname Name or designation of the target
ssomodel Name of the physical modelEPROC | DAMIT
ssomodelid Id of the physical model1..99
iauspin_ra Right ascension of the spin axisdeg
iauspin_dec Declination of the spin axisdeg
iauspin_w Longitude of the prime meridiandeg
iauspin_wp Rotation ratedeg/d
iauspin_tref Reference epoch of the prime meridian longitudejulian day
ssospinfile Existence of spin data according DAMIT databaseyes | no
ssoshapefile Existence of shape model according DAMIT databaseyes | no
ssoringfile Existence of ring definitionyes | no
ssofeaturefile Existence of features on the surface of the targetyes | 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:
VariableTypeUnitsLimits or valuesDefaultComment
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)
  1. See the HOWTO section for a full description about how to name targets.
  2. See the HOWTO section to known how to define the computation epoch.
  3. The physical models of objects can be gathered through the dedicated Miriade.ephemph GET API.
  4. See the HOWTO section to know how to define the observer location.
  5. See the HOWTO section for a description of the generated images.
  6. See the HOWTO section for a description of the syntax to pass arguments to the PSV image generator.
  7. 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
  1. 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.
  2. 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);
}