SolarSystem Class Reference

#include <SolarSystem.hpp>

Detailed Description

Class SolarSystem encapsulates the information in the JPL ephemeris file, both header and data, reading and writing of both ASCII and binary files, as well as the computation of position and velocity of the sun, moon and planets, plus nutations and lunar librations and their rates.

The user of this class should not have to read or write new files except either when the class is initially installed on a platform, or when a new ephemeris is obtained from JPL. Then procedure is first to download ASCII files for the desired ephemeris from the JPL ftp site at ftp://ssd.jpl.nasa.gov/pub/eph/planets. This consists of an ASCII header file (e.g. header.403) plus one or more ephemeris data files for the same ephemeris (e.g. ascp1975.403, ascp2000.403 and ascp2025.403 - these files contain the complete "DE403" ephemeris covering years 1975 to 2025). The user should then use a conversion program (such as convertEphemeris in the gpstk) to read these files and write out a single binary file for use in applications. Writing the binary file on the platform on which it is going to be used avoids potential problems with platform dependencies. The gpstk also includes a test program, testEphemeris, which will read a test file (also at the JPL ftp site) and compute several states, comparing them with JPL-generated 'truth' values; this will validate the generated binary file. To make use of this class and the generated binary file, the programmer simply instantiates a SolarSystem object, calls initializeWithBinaryFile(file) once, passing it the name of the binary file, then calling computeState() any number of times, passing it the time and Planet of interest.

Definition at line 67 of file SolarSystem.hpp.

Public Types

enum Planet {
  None = 0, Mercury, Venus, Earth,
  Mars, Jupiter, Saturn, Uranus,
  Neptune, Pluto, Moon, Sun,
  SolarSystemBarycenter, EarthMoonBarycenter, Nutations, Librations
}

These are indexes used by the caller of computeState(). More...

Public Member Functions

SolarSystem (void) throw ()

Constructor.

void readASCIIheader (std::string filename) throw (gpstk::Exception)

Read the header from a JPL ASCII planetary ephemeris file.

int readASCIIdata (std::vector< std::string > &filenames) throw (gpstk::Exception)

Read one or more ASCII data files.

int readASCIIdata (std::string filename) throw (gpstk::Exception)

Read only one ASCII data file.

int writeASCIIheader (std::ostream &os) throw (gpstk::Exception)

Write the header (ASCII) to an output stream
Exceptions:

if any stream error occurs.

int writeASCIIdata (std::ostream &os) throw (gpstk::Exception)

Write the stored data (ASCII) to an output stream NB.

int writeBinaryFile (std::string filename) throw (gpstk::Exception)

Write the header and the stored data to a binary output file.

void clearStorage (void) throw ()

clear the store map containing all the data read by readASCIIdata() or readBinaryData(true).

int readBinaryFile (std::string filename) throw (gpstk::Exception)

Read header and data from a binary file, storing ALL the data in store.

int initializeWithBinaryFile (std::string filename) throw (gpstk::Exception)

Open the given binary file, read the header and prepare for reading data records at random using seekToJD() and computing positions and velocities with computeState().

int computeState (double tt, Planet target, Planet center, double PV[6], bool kilometers=true) throw (gpstk::Exception)

Compute position and velocity of given 'target' body, relative to the 'center' body, at the given time.

double AU (void) throw ()

Return the value of 1 AU (Astronomical Unit) in km.

int JPLNumber (void) const throw ()

Return the ephemeris number.

double getConstant (std::string name) throw ()

gpstk::DayTime startTime (void) const throw (gpstk::Exception)

Return the start time of the data.

gpstk::DayTime endTime (void) const throw (gpstk::Exception)

Return the end time of the data.

gpstk::Position WGS84Position (Planet body, const gpstk::DayTime time, const gpstk::EarthOrientation &eo) throw (gpstk::Exception)

Return the geocentric (relative to Earth's center) position of a Solar System body at the input time, in WGS84 coordinates with units meters.

Member Enumeration Documentation

enum Planet

These are indexes used by the caller of computeState().

Enumeration values:

None 0 place holder

Mercury 1 Mercury

Venus 2 Venus

Earth 3 Earth

Mars 4 Mars

Jupiter 5 Jupiter

Saturn 6 Saturn

Uranus 7 Uranus

Neptune 8 Neptune

Pluto 9 Pluto

Moon 10 Moon (Geocentric coordinates)

Sun 11 Sun

SolarSystemBarycenter 12 Solar system barycenter

EarthMoonBarycenter 13 Earth-moon barycenter

Nutations 14 Nutations (psi, epsilon and their rates)

Librations 15 Lunar Librations (3 euler angles)

Definition at line 70 of file SolarSystem.hpp.

Constructor & Destructor Documentation

SolarSystem ( void ) throw () [inline]

Constructor.
Set EphemerisNumber to -1 to indicate that nothing has been read yet.
Definition at line 92 of file SolarSystem.hpp.

Member Function Documentation

double AU ( void ) throw () [inline]

Return the value of 1 AU (Astronomical Unit) in km.
If the file header has not been read, return -1.0.
Returns:
the value of 1 AU in km; return -1 if ephemeris has not been initialized.

Definition at line 213 of file SolarSystem.hpp.

void clearStorage ( void ) throw () [inline]

clear the store map containing all the data read by readASCIIdata() or readBinaryData(true).

Definition at line 151 of file SolarSystem.hpp.

int computeState ( double tt,

Planet target,

Planet center,

double PV[6],

bool kilometers = true

) throw (gpstk::Exception)

Compute position and velocity of given 'target' body, relative to the 'center' body, at the given time.
On successful return, PV contains position (in components 0-2) and velocity (components 3-5) (units: see param km) for regular bodies; for nutations and librations the units are radians and radians/day; nutations (components 0-3 only) are longitude or psi (component 0) and obliquity or epsilon (component 1) and their rates (components 2,3); librations (components 0-5) are the 3 euler angles in radians and their rates in radians/day.
Parameters:

tt Time (Julian Date) of interest.

target Body for which position and velocity are to be computed.

center Body relative to which the results apply. However, center may == SolarSystem::None, in which case the results are relative to the solar system barycenter. If target == Nutations or Librations, center is ignored.

PV Double array of length 6 containing output position and velocity components of target relative to center, in the order X,Y,Z,Vx,Vy,Vz. Units are determined by parameter km. If target == Nutations, PV contains 4 results, psi, eps, psi dot, eps dot in units radians and radians/day. If target == Librations, PV contains 3 euler angles in radians and their rates in radians/day.

km boolean: if true (default), units are km, km/day; else AU, AU/day (but not Nutations or Librations - see above).

Returns:
0 success, or (same as seekToJD()) -1 given time is before the first record in the file, -2 given time is after the last record, or in a gap between records, -3 input stream is not open or not valid, or EOF was found prematurely, -4 ephemeris is not initialized -3 or -4 => initializeWithBinaryFile() has not been called, or reading failed.

Definition at line 597 of file SolarSystem.cpp.
References gpstk::StringUtils::center(), GPSTK_RETHROW, and GPSTK_THROW.

gpstk::DayTime endTime ( void ) const throw (gpstk::Exception) [inline]

Return the end time of the data.

Definition at line 235 of file SolarSystem.hpp.
References DayTime::setMJD().

double getConstant ( std::string name ) throw () [inline]

Returns:
the value of the contant with the given name. If the header has not been read, return -1. Return zero if the constant is not found.

Definition at line 224 of file SolarSystem.hpp.

int initializeWithBinaryFile ( std::string filename ) throw (gpstk::Exception)

Open the given binary file, read the header and prepare for reading data records at random using seekToJD() and computing positions and velocities with computeState().
Does not store the data.
Parameters:

filename name of binary file to be read.

Returns:
0 success, -3 input stream is not open or not valid -4 header has not yet been read.

Exceptions:

if a gap in time is found between consecutive records.

Definition at line 568 of file SolarSystem.cpp.
References GPSTK_RETHROW, and GPSTK_THROW.

int JPLNumber ( void ) const throw () [inline]

Return the ephemeris number.

Returns:
JPL ephemeris number, e.g. 403, -1 if ephemeris has not been initialized.

Definition at line 219 of file SolarSystem.hpp.

int readASCIIdata ( std::string filename ) throw (gpstk::Exception)

Read only one ASCII data file.
Also see the documentation for the other version of this routine.
Parameters:

filename name of an ASCII data files (downloaded from JPL)

Returns:
0 ok, -1 if a stream error occurred, -4 header has not been read.

Exceptions:

if the header has not yet been read.

if the file could not be opened.

if any record has a 'number of coefficients' that differs from the header value.

Definition at line 223 of file SolarSystem.cpp.
References gpstk::StringUtils::asInt(), gpstk::StringUtils::asString(), gpstk::StringUtils::for2doub(), GPSTK_RETHROW, GPSTK_THROW, gpstk::StringUtils::stripFirstWord(), and gpstk::StringUtils::stripTrailing().

int readASCIIdata ( std::vector< std::string > & filenames ) throw (gpstk::Exception)

Read one or more ASCII data files.
Call only after having read the header, and call only with data files for the same ephemeris as the header (the JPL files are named 'header.NNN' and 'ascSYYYY.NNN' where NNN is the ephemeris number (appears inside the header file, but not inside the data files), S is either 'p' or 'n' as the year is positive or negative (AD or BC), and YYYY is the year of the first record in the file.
Parameters:

filenames vector containting the names of the ASCII data files (downloaded from JPL), in any order.

Returns:
0 ok, -1 if a stream error occurred.

Exceptions:

if the header has not yet been read.

if any file could not be opened.

if any record in any file has a 'number of coefficients' that differs from the header value.

Definition at line 182 of file SolarSystem.cpp.
References GPSTK_RETHROW, GPSTK_THROW, gpstk::StringUtils::leftJustify(), DayTime::printf(), and DayTime::setMJD().

void readASCIIheader ( std::string filename ) throw (gpstk::Exception)

Read the header from a JPL ASCII planetary ephemeris file.
Note that this routine clears the 'store' map and defines the 'constants' hash. It also sets EphemerisNumber to the constant "DENUM" if successful.
Parameters:

filename the name of the ASCII header file.

Exceptions:

if the file cannot be opened.

if the header ends prematurely or if it is not properly formatted.

if any stream error occurs.

Definition at line 37 of file SolarSystem.cpp.
References gpstk::StringUtils::asInt(), gpstk::StringUtils::asString(), gpstk::StringUtils::for2doub(), GPSTK_RETHROW, GPSTK_THROW, gpstk::StringUtils::stripFirstWord(), gpstk::StringUtils::stripLeading(), gpstk::StringUtils::stripTrailing(), and gpstk::StringUtils::word().

int readBinaryFile ( std::string filename ) throw (gpstk::Exception)

Read header and data from a binary file, storing ALL the data in store.
For use with copying, merging or editing data files. Closes the stream before returning.
Parameters:

filename name of binary file to be read.

Returns:
0 success, -3 input stream is not open or not valid -4 header has not yet been read.

Exceptions:

if a gap in time is found between consecutive records.

Definition at line 550 of file SolarSystem.cpp.
References GPSTK_RETHROW, and GPSTK_THROW.

gpstk::DayTime startTime ( void ) const throw (gpstk::Exception) [inline]

Return the start time of the data.

Definition at line 231 of file SolarSystem.hpp.
References DayTime::setMJD().

Position WGS84Position ( Planet body,

const gpstk::DayTime time,

const gpstk::EarthOrientation & eo

) throw (gpstk::Exception)

Return the geocentric (relative to Earth's center) position of a Solar System body at the input time, in WGS84 coordinates with units meters.

Returns:
Position of the planet relative to Earth center.

Parameters:

body SolarSystem::Planet of interest (input)

time Time of interest (input)

eo Earth orientation at time (cf class EarthOrientation) (input)

Definition at line 685 of file SolarSystem.cpp.
References GPSTK_RETHROW, GPSTK_THROW, DayTime::MJD(), Position::setECEF(), and gpstk::transpose().

int writeASCIIdata ( std::ostream & os ) throw (gpstk::Exception)

Write the stored data (ASCII) to an output stream NB.
This routine does NOT clear the store - use clearStorage()
Exceptions:

if any stream error occurs

Returns:
0 success, -4 header has not yet been read.

Definition at line 389 of file SolarSystem.cpp.
References gpstk::StringUtils::doub2for(), GPSTK_RETHROW, GPSTK_THROW, and gpstk::StringUtils::leftJustify().

int writeASCIIheader ( std::ostream & os ) throw (gpstk::Exception)

Write the header (ASCII) to an output stream
Exceptions:

if any stream error occurs.

Returns:
0 success, -4 header has not yet been read.

Definition at line 303 of file SolarSystem.cpp.
References gpstk::StringUtils::asString(), gpstk::StringUtils::doub2for(), GPSTK_RETHROW, GPSTK_THROW, gpstk::StringUtils::leftJustify(), and gpstk::StringUtils::rightJustify().

int writeBinaryFile ( std::string filename ) throw (gpstk::Exception)

Write the header and the stored data to a binary output file.
NB. This routine does NOT clear the store - use clearStorage()
Parameters:

filename name of binary file to be read.

Returns:
0 ok -4 if data has not been read into the object

Exceptions:

if any stream error occurs.

Definition at line 432 of file SolarSystem.cpp.
References GPSTK_RETHROW, GPSTK_THROW, and gpstk::StringUtils::leftJustify().

The documentation for this class was generated from the following files:

Generated on Wed Feb 8 03:31:27 2012 for GPS ToolKit Software Library by

1.3.9.1