SkyMap coordinates
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 (xC, yC, zC) ("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, qC, jC), its cartesian coordinates (xC, yC, zC) are then given by :
  • xC = cosqC cos jC
  • yC = sinqC cos jC
  • zC = sin jC
  • (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, qC corresponds to right ascension (noted a or ra), and jC 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 (xE, yE, zE) ; the corresponding spherical coordinates will be (1, qE, jE)

    In the eye frame, the viewer is oriented as follows :
  • he (or she) looks towards the positive direction of axis OzE ;
  • he (or she) is facing the positive direction of axis OyE ;
  • the positive direction of axis OxE 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 XC in sky frame, and by XE in the eye frame, we simply have :
    XE = E XC
    and :
    XC = E-1 XE

    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 (xS, yS).

    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, qE, jE), its screen coordinates are :
  • xS = cosqE cos jE
  • yS = sinqE cos jE
  • zS = 0

  • Here, we note that xS = xE and yS = yE. This is the case only because an orthogonal projection is used.

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

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

    Pixel coordinates

    The last coordinates to define are the pixel coordinates, noted (xP, yP).
    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 (xS, yS) and pixel (xP, yP) 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 :
  • xP = -r xS + w/2
  • yP = -r yS + w/2
  • and
  • xS = (-xP + w/2)/r
  • yS = (-yP + w/2)/r
  • Summary of notations

    In this page, the following coordinates were introduced :
  • the sky coordinates (xC, yC, zC) ;
  • the eye coordinates (xE, yE, zE) ;
  • the screen coordinates (xS, yS, 0) ;
  • the pixel coordinates (xP, yP, 0).

  • These names were used in the code.