	Units
	Units Role of units in the API Units API To display ephemeris, the program gives coordinates of position or velocity vectors. To express these coordinates, we need units. So the program must identify units. This is done with constants of class `jephem.astro.spacetime.UnitConstants`. Related methods can be found in class `jephem.astro.spacetime.Units`

Units

The program handles linear distances and angular measures, and their derivates with respect to time.
Among all the possible units to express these quantities, here is what the first version of the program recognizes :

	distance	velocity
linear	m km ua	m/s km/h km/d au/d
angular	arcsec deg rad	arcsec/s arcsec/d deg/s deg/d rad/d

Notations :
arcsec : arc second
deg : degree
h : hour
km : kilometer
m : meter
rad : radian
s : second (for time)
au : astronomical unit

This classification was used to name the constants of UnitsConstants. So constants to designate units are named :

DISTANCE_UNIT_XXX, (ex : DISTANCE_UNIT_KM)

LINEAR_SPEED_UNIT_XXX,

ANGULAR_UNIT_XXX and

ANGULAR_SPEED_UNIT_XXX.

Note : in a flexible program, it should be possible to specify velocity units with two characteristics
- The distance unit
- The time unit
If this becomes useful, it could be implemented in future versions.

Class UnitConstants also holds constants to designate unit type (units can be 'angular' units, 'distance' units etc..) :

TYPE_DISTANCE

TYPE_LINEAR_SPEED

TYPE_ANGULAR

TYPE_ANGULAR_SPEED

Several methods need an array of integers to express the units. This is for example the case of AstroContext.calcBodyCoords(). The notion of unit group was developped to conveniently express particular groups of commonly used units.
Example : the code
int[] units = new int[]{DISTANCE_UNIT_AU, DISTANCE_UNIT_AU, DISTANCE_UNIT_AU};
can be replaced by :
int[] units = UNITGROUP_AU_AU_AU;

See Units' javadoc page for more details.

Role of units in the API

Instances of class Body need to store the units used to express their coordinates. This is done with two arrays of 3 integers that can be accessed through Body's methods :
- public int[] getPositionUnits()
- public int[] getVelocityUnits()
- public void setPositionUnits(int[] posUnits)
- public void setVelocityUnits(int[] posUnits)

It is planetary theories' responsability to first fill the positionUnits and velocityUnits of bodies.

These units are eventually changed by methods that perform coordinate transformation (like sphereToCart() and cartToSphere() in class Body).

They are used by higer level class (like Ephemeris) which display the coordinates.

`Units` API

Apart from holding constants, Units provides these methods :

public static double[] convertUnits(double[] coords, int[] units1, int[] units2), to convert coordinates between a set of units to an other.

public static String getUnitLabel(int unit), to get the english name of a unit.

public static String getUnitLabels(int unitType), to get the english names of all units of a certain type.

Note : Higher level classes, like jephem.astro.tools.Ephemeris don't use the two last methods, because they use labels stored in ressource files.
I put labels here to permit the astro API to work independently from other classes (cf Keeping astro classes independent for details).

Units is an abstract class. All its fields and methods are static.

JEphem Presentation Ephemeris SkyMap Curve Date search Informatic Library Download Glossary About
	JEphem Ephemeris trail Units

Units

Role of units in the API

Units API

`Units` API