API user guide

Independance of the astro API Setting the files Ordering a computation

The purpose of this page is to present the main points to consider for developers who would like to use JEphem as an astro library in their programs.
The non astro part is not considered here. More details can be found in other pages of this trail.

Independance of the astro API

JEphem was developped to be used in two different ways :

as an autonom application (including the user interface and its different mechanims, like internationalization, preferences...) ;

as an astro library, includable in other programs.

This implies that all dependencies have been removed from classes of jephem.astro.* packages.
Because of this exigence, higher level classes (like jephem.tools.Ephemeris), which use preferences or internationalization, had to be put in an other package.

Setting the files

Including tig package

Before using JEphem, one must include tig.jar in the classpath (cf download area). It contains generic classes, whose code has been separated from JEphem to be reusable. In fact, only a few classes from tig package are used by astro classes :

All classes of package tig.maths

class tig.GeneralConstants

class Formats

Some test methods (which are commented but still present in JEphem's code) also use class tig.Strings.

Having the data files

Some classes (VSOP87, ELP82) need data files to perform the computations.
These files are located in JEphem directory/data/astro.
Classes needing data have a static method setDataPath(), which must be called before using the class.

Ordering a computation

Before trying to use JEphem, you can have a quick look at the ephemeris trail, and in particular the pages class organization and Putting all together.

To compute coordinates for one date, build a jephem.astro.AstroContext and call its method calcBodyCoords().
The coordinates can then be retrieved from the AstroContext's bodies.

Here is code example to perform such a task :

import jephem.astro.AstroContext;
import jephem.astro.Body;
import jephem.astro.SolarSystemConstants;
import jephem.astro.SolarSystem;
import jephem.astro.spacetime.SpaceConstants;
import jephem.astro.spacetime.UnitConstants;

public class testJEphem implements SolarSystemConstants, UnitConstants, SpaceConstants{
  
  public static void main(String[] args){

    // Build the AstroContext
    int[] bodyIndexes = {SUN, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, NEPTUNE, PLUTO};
    double jd = 245897.52;
    AstroContext ac = new AstroContext(jd, bodyIndexes);

    // Prepare the variables
    int frame = GEOCENTRIC_ECLIPTIC;
    int sphereCart = SPHERICAL;
    double precision = 1.0;
    int[] units = {DISTANCE_UNIT_AU, ANGULAR_UNIT_DEG, ANGULAR_UNIT_DEG,
                   LINEAR_SPEED_UNIT_AU_PER_D, ANGULAR_SPEED_UNIT_DEG_PER_DAY, ANGULAR_SPEED_UNIT_DEG_PER_DAY};
    boolean velocities = true;

    // order the computation    
    ac.calcBodyCoord(frame, 
                     sphereCart, 
                     precision,
                     velocities,
                     units);

   // Display the coordinates
   Body[] bodies = ac.getBodies();
   Body curBody;
   int coordGroup = Space.getCoordGroup(frame, sphereCart);
   String[] coordLabels = Space.getCoordLabels(coordGroup);
   int[] units;
   for(int i = 0; i < bodies.length; i++){
     curBody = bodies[i];
     System.out.println(curBody.getName() + " : ");
     units = curBody.getPositionUnits();
     for(j = 0; j < 3; j++){
       System.out.println("  " + coordLabels[j] + " : " + curBody.getCoord(j) + "  " + Units.getUnitLabel(units[j]));
     }
     if(velocities){
       units = curBody.getVelocityUnits();
       for(int j = 0; j < 3; j++){
         System.out.println("  d(" + coordLabels[j] + ")/dt : " +  curBody.getCoord(j+3) + "  " + Units.getUnitLabel(units[j]));
        }
      }
    }// end for i

  }// end main()
  
}// end class

Result of the execution :

to do

'bodies' is an array of integers containing constants of ISolarSystemConstants.java, representing bodies of the solar system. It indicates which bodies will be considered by the AstroContext.

The main method of AstroContext is calcBodyCoord, which takes as parameters :

    - The reference frame in which the coordinates must be expressed ;
    - The way to express the coordinates (cartesian or spherical) ;
    - The precision of the calculations (expressec in arcseconds) ;
    - A boolean indicating if the velocities must be computed. If set to false, only the positions are calculated.

Depending on 'precision' and its bodies, the AstroContext will call low-level classes to perform the computations.

If precision can't be handled by the specified theories, an AstroException is stored in the concerned Body.

To compute coordinates for several dates, the class to use is jephem.tools.Ephemeris

`Independence of astro classes`

The astro classes have been developped to be completely independent from the rest of the application, to have the possibility to use JEphem as a library. So to use JEphem only as a library, one should use only the package jephem.astro.

`Exception handling`

The classes from packages undes jephem.astro throw only AstroExceptions and IllegalArgumentExceptions.

In the case of jephem.astro.planets.ComputationExceptions, they are stored in the bodies, and can be used by client calsses.

These exceptions must be caught by client classes. In the case of JEphem GUI, they are sent to jephem.util.Debug.

The non-astro classes either directly use Debug or redirect the exceptions via JEphemExceptions.

JEphem Presentation Ephemeris SkyMap Curve Informatic Library Download Glossary About
	JEphem Informatic trail API user guide