	SkyMap coordinates
	Sky coordinates Viewer coordinates Screen coordinates Pixel coordinates Summary To draw a sky map, we need to consider the sky, the viewer, and the screen. The purpose is to present the involved coordinates.

Sky coordinates

The star catalogs give coordinates of the stars expressed in the equatorial frame.
The purpose is to get the true apparent coordinates at a given date.
The corrections to apply to the coordinates as given in the catalogs are :

Transformation from catalog's frame to ICRF ;

Proper Motion of the stars ;

Precession, nutation, aberration, if the viewer is in a frame linked to the Earth ; these transformations should also be applied if the viewer is in a Frame linked to an other planet ;

Refraction, if the viewer is in a horizontal topocentric frame.

In sky map context, the frame in which the coordinates of the represented celestial bodies are expressed is called the sky frame.
Coordinates expressed in this frame will be called sky coordinates and noted (x_C, y_C, z_C) ("C" stands for "celestial").
In sky map context, we consider that the bodies are located on a sphere. The radius of this sphere can be arbitrarily choosen ; to simplify, we'll consider it equal to 1.
If the spherical coordinates of a body are (1, q_C, j_C), its cartesian coordinates (x_C, y_C, z_C) are then given by :

x_C = cosq_C cos j_C

y_C = sinq_C cos j_C

z_C = sin j_C

(see the page about spherical and cartesian coordinates for more details).

In general, the sky frame is the equatorial frame. The SkyMap API provides a way to change it via methods getSkyFrame() and setSkyFrame() of class SkyMap.
In the equatorial frame, q_C corresponds to right ascension (noted a or ra), and j_C to declination (noted d or dec).

Viewer or Eye coordinates

We'll consider that the viewer is composed of a single eye, located at the center of the sky frame. In SkyMap context, viewer and eye are considered as equivalent. However, eye was used to name the related methods and variables. The distinction between the viewer and its eye may become important if JEphem is used in a Java3D context.

In sky map context, the viewer can't move, he's stuck at the center of the sky frame. But he is allowed to turn his head. His orientation is defined by the eye matrix.
The viewer's orientation is detailed in an other page.

The eye matrix defines the orientation of the eye frame in the sky frame.
Coordinates expressed in the eye frame will be called eye coordinates and noted (x_E, y_E, z_E) ; the corresponding spherical coordinates will be (1, q_E, j_E)

In the eye frame, the viewer is oriented as follows :

he (or she) looks towards the positive direction of axis Oz_E ;

he (or she) is facing the positive direction of axis Oy_E ;

the positive direction of axis Ox_E is then at his (her) right.

Transformations between sky and eye coordinates

Let's call E the eye matrix. If cartesian coordinates of a point are expressed by vector X_C in sky frame, and by X_E in the eye frame, we simply have :

X_E = E X_C

and :

X_C = E^-1 X_E

Screen coordinates

Let's call screen plane the reference plane of the eye frame. The celestial bodies will be projected on this plane to be rendered on the screen.
The coordinates of the projected point are called screen coordinates and noted (x_S, y_S).

I couldn't find documentation on the projection used to draw sky maps. So I used a simple orthogonal projection on the screen plane :

Transformations between screen and eye coordinates

If the spherical coordinates of a point in the eye frame are (1, q_E, j_E), its screen coordinates are :

x_S = cosq_E cos j_E

y_S = sinq_E cos j_E

z_S = 0

Here, we note that x_S = x_E and y_S = y_E. This is the case only because an orthogonal projection is used.

To get the eye coordinates from the screen coordinates, we have :

tanq_E can be obtained between 0 and 2p through tig.maths.Maths.arctan3(double x, double y).
To get j_E, the function java.lang.Math.acos() will return a angle between 0 and p/2. This will be correct as we know that z_E > 0.

Pixel coordinates

The last coordinates to define are the pixel coordinates, noted (x_P, y_P).
They correspond to the coordinates used by the computer to render a point on the display area.

Transformations between screen and pixel coordinates

Here, we must take care of something : as the user looks from below, the direct frame transforms to an indirect frame on the screen plane :

To express the transformation between screen (x_S, y_S) and pixel (x_P, y_P) coordinates, we need a supplementary definition : the sphere will be projected as a circle on the screen plane. We'll call r the radius of this circle, in pixel ; the value of r depends on the zoom factor (see the zoom page).
Noting h and w the height and the width of the display area, the transformations are :

x_P = -r x_S + w/2

y_P = -r y_S + w/2

and

x_S = (-x_P + w/2)/r

y_S = (-y_P + w/2)/r

Summary of notations

In this page, the following coordinates were introduced :

the sky coordinates (x_C, y_C, z_C) ;

the eye coordinates (x_E, y_E, z_E) ;

the screen coordinates (x_S, y_S, 0) ;

the pixel coordinates (x_P, y_P, 0).

These names were used in the code.

JEphem Presentation Ephemeris SkyMap Curve Date search Informatic Library Download Glossary About
	JEphem Sky map SkyMap coordinates