/** @file  psAstrometry.c
 *
 *  @brief This file defines the basic types for astronomical coordinate
 *  transformation
 *
 *  @ingroup AstroImage
 *
 *  @author George Gusciora, MHPCC
 *
 *  @version $Revision: 1.42 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2004-10-14 23:45:53 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
 */

/******************************************************************************/
/*  INCLUDE FILES                                                             */
/******************************************************************************/
#include <string.h>
#include <math.h>

#include "psFunctions.h"
#include "psAstrometry.h"
#include "psMemory.h"
#include "psAbort.h"
#include "psError.h"
#include "psConstants.h"
#include "slalib.h"

/*****************************************************************************
checkValidImageCoords(): this is a private function which simply
determines if the supplied x,y coordinates are in the range for the supplied
psImage.
 *****************************************************************************/
static int checkValidImageCoords(double x,
                                 double y,
                                 psImage* tmpImage)
{
    if (tmpImage == NULL) {
        return(0);
    }

    if ((x < 0.0) ||
            (x > (double)tmpImage->numCols) ||
            (y < 0.0) ||
            (y > (double)tmpImage->numRows)) {
        return (0);
    }

    return (1);
}

/*****************************************************************************
isProjectionLinear(): this is a private function which simply determines
if the supplied psPlaneTransform transform is linear: if any of the
cooefficients of order 2 are higher are non-zero, then it is not linear.
 *****************************************************************************/
static int isProjectionLinear(psPlaneTransform *transform)
{
    int i = 0;
    PS_CHECK_NULL_PTR_RETURN_ZERO(transform);

    for (i=2;i<(transform->x->nX);i++) {
        if (transform->x->coeff[i][0] != 0.0) {
            return(0);
        }
    }
    for (i=2;i<(transform->x->nY);i++) {
        if (transform->x->coeff[0][i] != 0.0) {
            return(0);
        }
    }

    for (i=2;i<(transform->y->nX);i++) {
        if (transform->y->coeff[i][0] != 0.0) {
            return(0);
        }
    }
    for (i=2;i<(transform->y->nY);i++) {
        if (transform->y->coeff[0][i] != 0.0) {
            return(0);
        }
    }

    return(1);
}

/*****************************************************************************
invertPlaneTransform(transform): : this is a private function which
simply inverts the supplied psPlaneTransform transform.  It assumes that
"transform" is linear.
 
This program assumes that the inverse of the following linear equations:
        X2 = A + (B * X1) + (C * Y1);
        Y2 = D + (E * X1) + (F * Y1);
is
        Y1 = (Y2 - ((E/B) * X2) - D + ((E*A)/B)) / (F - ((C*E)/B));
        X1 = (Y2 - ((F/C) * X2) - D + ((F*A)/C)) / (E - ((F*B)/C));
or
 X1 = (-D + ((F*A)/C)) / (E - ((F*B)/C)) +
      (X2 * -((F/C) / (E - ((F*B)/C)))) +
             (Y2 * (1.0 / (E - ((F*B)/C))));
        Y1 = (-D + ((E*A)/B))/(F - ((C*E)/B)) +
             (X2 * -((E/B) / (F - ((C*E)/B)))) +
             (Y2 * (1.0 / (F - ((C*E)/B))));
 *****************************************************************************/
static psPlaneTransform *invertPlaneTransform(psPlaneTransform *transform)
{
    double A = transform->x->coeff[0][0];
    double B = transform->x->coeff[1][0];
    double C = transform->x->coeff[0][1];
    double D = transform->y->coeff[0][0];
    double E = transform->y->coeff[1][0];
    double F = transform->y->coeff[0][1];

    PS_CHECK_NULL_PTR_RETURN_NULL(transform);
    psPlaneTransform *out = psAlloc(sizeof(psPlaneTransform));

    out->x->coeff[0][0] = -D + ((F*A)/C) / (E - ((F*B)/C));
    out->x->coeff[1][0] = -(F/C) / (E - ((F*B)/C));
    out->x->coeff[0][1] =  1.0 / (E - ((F*B)/C));
    out->y->coeff[0][0] = -D + ((E*A)/B) / (F - ((C*E)/B));
    out->y->coeff[1][0] = -(E/B) / (F - ((C*E)/B));
    out->y->coeff[0][1] =  1.0 / (F - ((C*E)/B));

    return(out);
}

static void FPAFree(psFPA* fpa)
{
    if (fpa != NULL) {
        psFree(fpa->chips);
        psFree(fpa->grommit);
        psFree((psExposure*)fpa->exposure);
        psFree(fpa->metadata);
        psFree(fpa->fromTangentPlane);
        psFree(fpa->toTangentPlane);
        psFree(fpa->pattern);
        psFree(fpa->colorPlus);
        psFree(fpa->colorMinus);
        psFree(fpa->projection);
    }
}

static void chipFree(psChip* chip)
{
    if (chip != NULL) {
        psFree(chip->cells);
        psFree(chip->metadata);
        psFree(chip->toFPA);
        psFree(chip->fromFPA);
    }
}

static void cellFree(psCell* cell)
{
    if (cell != NULL) {
        psFree(cell->readouts);
        psFree(cell->metadata);
        psFree(cell->toChip);
        psFree(cell->fromChip);
        psFree(cell->toFPA);
        psFree(cell->toTP);
    }
}

static void readoutFree(psReadout* readout)
{
    if (readout != NULL) {
        psFree(readout->image);
        psFree(readout->mask);
        psFree(readout->objects);
        psFree(readout->metadata);
    }
}

static void observatoryFree(psObservatory* obs)
{
    if (obs != NULL) {
        psFree((void*)obs->name);
    }
}

static void exposureFree(psExposure* exp)
{
    if (exp != NULL) {
        psFree((void*)exp->time);
        psFree((void*)exp->observatory);
        psFree((void*)exp->cameraName);
        psFree((void*)exp->telescopeName);
    }
}

static void fixedPatternFree(psFixedPattern* fp)
{
    if (fp != NULL) {
        for (int i = 0; i < fp->p_ps_xRows; i++) {
            psFree(fp->x[i]);
        }

        for (int j = 0; j < fp->p_ps_yRows; j++) {
            psFree(fp->y[j]);
        }

        psFree(fp->x);
        psFree(fp->y);
    }
}

/*****************************************************************************/
/* FUNCTION IMPLEMENTATION - PUBLIC                                          */
/*****************************************************************************/


/*
 * XXX: Verify that you interpreted the SDR correctly.
 *
 * XXX: This assumes that x,y must be of type F64
 */
psFixedPattern* psFixedPatternAlloc(double x0,
                                    double y0,
                                    double xScale,
                                    double yScale,
                                    const psImage *x,
                                    const psImage *y)
{
    psFixedPattern *tmp;
    int i;
    int j;

    PS_CHECK_NULL_IMAGE_RETURN_NULL(x);
    PS_CHECK_NULL_IMAGE_RETURN_NULL(y);
    PS_CHECK_IMAGE_TYPE_RETURN_NULL(x, PS_TYPE_F64);
    PS_CHECK_IMAGE_TYPE_RETURN_NULL(y, PS_TYPE_F64);

    tmp = (psFixedPattern *) psAlloc(sizeof(psFixedPattern));
    // XXX: Is this correct?
    tmp->nX = (x->numCols * x->numRows);
    tmp->nY = (y->numCols * y->numRows);
    tmp->x0 = x0;
    tmp->y0 = y0;
    tmp->xScale = xScale;
    tmp->yScale = yScale;
    tmp->p_ps_xRows = x->numRows;
    tmp->p_ps_xCols = x->numCols;
    tmp->p_ps_yRows = y->numRows;
    tmp->p_ps_yCols = y->numCols;
    tmp->x = (double **) psAlloc(x->numRows * sizeof(double *));
    for (i=0;i<x->numRows;i++) {
        (tmp->x)[i] = (double *) psAlloc(x->numCols * sizeof(double));
    }
    for (i=0;i<x->numRows;i++) {
        for (j=0;j<x->numCols;j++) {
            (tmp->x)[i][j] = x->data.F64[i][j];
        }
    }

    tmp->y = (double **) psAlloc(y->numRows * sizeof(double *));
    for (i=0;i<y->numRows;i++) {
        (tmp->y)[i] = (double *) psAlloc(y->numCols * sizeof(double));
    }
    for (i=0;i<y->numRows;i++) {
        for (j=0;j<y->numCols;j++) {
            (tmp->y)[i][j] = y->data.F64[i][j];
        }
    }

    p_psMemSetDeallocator(tmp,(psFreeFcn)fixedPatternFree);

    return(tmp);
}


psExposure* psExposureAlloc(double ra,
                            double dec,
                            double hourAngle,
                            double zenithDistance,
                            double azimuth,
                            const psTime* time,
                            float rotAngle,
                            float temperature,
                            float pressure,
                            float humidity,
                            float exposureTime,
                            float wavelength,
                            const psObservatory* observatory)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(observatory);
    psExposure* exp = psAlloc(sizeof(psExposure));

    *(double *)&exp->ra = ra;
    *(double *)&exp->dec = dec;
    *(double *)&exp->hourAngle = hourAngle;
    *(double *)&exp->zenithDistance = zenithDistance;
    *(double *)&exp->azimuth = azimuth;
    *(float *)&exp->rotAngle = rotAngle;
    *(float *)&exp->temperature = temperature;
    *(float *)&exp->pressure = pressure;
    *(float *)&exp->humidity = humidity;
    *(float *)&exp->exposureTime = exposureTime;
    *(float *)&exp->wavelength = wavelength;

    exp->time = psMemIncrRefCounter((void*)time);
    exp->observatory = psMemIncrRefCounter((void*)observatory);

    // XXX: how is these value derived?
    *(double *)&exp->lst = psTimeToLST((psTime*)time,observatory->longitude);
    *(float *)&exp->positionAngle = 0.0f; // XXX: need input, see Bug #207
    *(float *)&exp->parallacticAngle = 0.0f; // XXX: need input, see Bug #207
    *(float *)&exp->airmass = slaAirmas(zenithDistance);
    *(float *)&exp->parallacticFactor = 0.0f;
    exp->cameraName = NULL;
    exp->telescopeName = NULL;

    p_psMemSetDeallocator(exp,(psFreeFcn)exposureFree);

    return exp;
}

psObservatory* psObservatoryAlloc(const char* name,
                                  double latitude,
                                  double longitude,
                                  double height,
                                  double tlr)
{
    psObservatory* obs = psAlloc(sizeof(psObservatory));

    if (name == NULL) {
        obs->name = NULL;
    } else {
        obs->name = psAlloc(strlen(name)+1);
        strcpy((char*)obs->name, name);
    }

    *(double *)&obs->latitude = latitude;
    *(double *)&obs->longitude = longitude;
    *(double *)&obs->height = height;
    *(double *)&obs->tlr = tlr;

    p_psMemSetDeallocator(obs,(psFreeFcn)observatoryFree);

    return obs;
}

psFPA* psFPAAlloc(int nChips,
                  const psExposure* exp)
{
    psFPA* newFPA = psAlloc(sizeof(psFPA));

    // create array of NULL chips of the size nChips
    newFPA->chips = psArrayAlloc(nChips);
    void** chips = newFPA->chips->data;
    for (int i=0;i<nChips;i++) {
        chips[i] = NULL;
    }

    newFPA->metadata = NULL;
    newFPA->fromTangentPlane = NULL;
    newFPA->toTangentPlane = NULL;
    newFPA->pattern = NULL;

    if (exp != NULL) {
        newFPA->exposure = psMemIncrRefCounter((psExposure*)exp);
        newFPA->grommit = psGrommitAlloc(exp);
    } else {
        newFPA->exposure = NULL;
        newFPA->grommit = NULL;
    }

    newFPA->colorPlus = NULL;
    newFPA->colorMinus = NULL;
    newFPA->projection = NULL;

    newFPA->rmsX = 0.0f;
    newFPA->rmsY = 0.0f;
    newFPA->chi2 = 0.0f;

    p_psMemSetDeallocator(newFPA,(psFreeFcn)FPAFree);

    return newFPA;
}

/*
 * psChip constructor
 */
psChip* psChipAlloc(int nCells,
                    psFPA *parentFPA)
{
    psChip* chip = psAlloc(sizeof(psChip));

    // create array of NULL psCells
    chip->cells = psArrayAlloc(nCells);
    void** cells = chip->cells->data;
    for (int i=0;i<nCells;i++) {
        cells[i] = NULL;
    }

    chip->metadata = NULL;

    chip->toFPA = NULL;
    chip->fromFPA = NULL;

    chip->parent = parentFPA;

    p_psMemSetDeallocator(chip,(psFreeFcn)chipFree);

    return chip;

}

/*
 * psCell constructor
 */
psCell* psCellAlloc(int nReadouts,
                    psChip* parentChip)
{
    psCell* cell = psAlloc(sizeof(psCell));

    // create array of NULL psReadouts
    cell->readouts = psArrayAlloc(nReadouts);
    void** readouts = cell->readouts->data;
    for (int i=0;i<nReadouts;i++) {
        readouts[i] = NULL;
    }

    cell->metadata = NULL;

    cell->toChip = NULL;
    cell->fromChip = NULL;
    cell->toFPA = NULL;
    cell->toTP = NULL;

    cell->parent = parentChip;

    p_psMemSetDeallocator(cell,(psFreeFcn)cellFree);

    return cell;


}

psReadout* psReadoutAlloc(int col0,
                          int row0,
                          const psImage* image)
{
    psReadout* readout = psAlloc(sizeof(psReadout));

    *(unsigned int*)&readout->colBins = 1;
    *(unsigned int*)&readout->rowBins = 1;
    *(int*)&readout->col0 = col0;
    *(int*)&readout->row0 = row0;

    readout->image = (psImage*)image;
    readout->mask = NULL;
    readout->objects = NULL;
    readout->metadata = NULL;

    p_psMemSetDeallocator(readout,(psFreeFcn)readoutFree);

    return readout;
}

psGrommit* psGrommitAlloc(const psExposure* exp)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(exp);

    double date = psTimeToMJD(exp->time);
    double dut = psTimeGetUT1Delta(exp->time);
    double elongm = exp->observatory->longitude;
    double phim = exp->observatory->latitude;
    double hm = exp->observatory->height;

    psSphere* polarMotion = psTimeGetPoleCoords(exp->time);
    double xp = polarMotion->r;
    double yp = polarMotion->d;
    psFree(polarMotion);

    double tdk = exp->temperature;
    double pmb = exp->pressure;
    double rh = exp->humidity;
    double wl = exp->wavelength;
    double tlr = exp->observatory->tlr;

    psGrommit* grommit = (psGrommit* ) psAlloc(sizeof(psGrommit));

    slaAoppa(date, dut, elongm, phim, hm, xp, yp,
             tdk, pmb, rh, wl, tlr, (double*)grommit);

    return (grommit);
}

psCell* psCellInFPA(const psPlane* fpaCoord,
                    const psFPA* FPA)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(fpaCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(FPA);
    psChip* tmpChip = NULL;
    psPlane chipCoord;
    psCell* outCell = NULL;

    // Determine which chip contains the fpaCoords.
    tmpChip = psChipInFPA(fpaCoord, FPA);
    if (tmpChip == NULL) {
        return(NULL);
    }

    // Convert to those chip coordinates.
    psCoordFPAToChip(&chipCoord, fpaCoord, tmpChip);

    // Determine which cell contains those chip coordinates.
    outCell = psCellInChip(&chipCoord, tmpChip);

    return (outCell);
}

psChip* psChipInFPA(const psPlane* fpaCoord,
                    const psFPA* FPA)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(fpaCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(FPA);
    PS_CHECK_NULL_PTR_RETURN_NULL(FPA->chips);
    psArray* chips = FPA->chips;
    int nChips = chips->n;
    psPlane chipCoord;
    psCell *tmpCell = NULL;

    // Loop through every chip in this FPA.  Convert the original FPA
    // coordinates to chip coordinates for that chip.  Then, determine if any
    // cells in that chip contain those chip coordinates.

    for (int i = 0; i < nChips; i++) {
        psChip* tmpChip = chips->data[i];
        psPlaneTransformApply(&chipCoord, tmpChip->fromFPA, fpaCoord);

        tmpCell = psCellInChip(&chipCoord, tmpChip);
        if (tmpCell != NULL) {
            return(tmpChip);
        }
    }

    return (NULL);
}

psCell* psCellInChip(const psPlane* chipCoord,
                     const psChip* chip)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(chipCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(chip);

    psPlane cellCoord;
    psArray* cells;

    cells = chip->cells;
    if (cells == NULL) {
        return NULL;
    }

    // We loop over each cell in the chip.  We transform the chipCoord into
    // a cellCoord for that cell and determine if that cellCoord is valid.
    // If so, then we return that cell.

    for (int i = 0; i < cells->n; i++) {
        psCell* tmpCell = (psCell* ) cells->data[i];
        psArray* readouts = tmpCell->readouts;

        if (readouts != NULL) {
            for (int j = 0; j < readouts->n; j++) {
                psReadout* tmpReadout = readouts->data[j];

                psPlaneTransformApply(&cellCoord,
                                      tmpCell->fromChip,
                                      chipCoord);

                if (checkValidImageCoords(cellCoord.x,
                                          cellCoord.y,
                                          tmpReadout->image)) {
                    return (tmpCell);
                }
            }
        }
    }

    return (NULL);
}

psPlane* psCoordCellToChip(psPlane* outCoord,
                           const psPlane* inCoord,
                           const psCell* cell)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(inCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(cell);

    return (psPlaneTransformApply(outCoord, cell->toChip, inCoord));
}

psPlane* psCoordChipToFPA(psPlane* outCoord,
                          const psPlane* inCoord,
                          const psChip* chip)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(inCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(chip);

    return (psPlaneTransformApply(outCoord, chip->toFPA, inCoord));
}

psPlane* psCoordFPAToTP(psPlane* outCoord,
                        const psPlane* inCoord,
                        double color,
                        double magnitude,
                        const psFPA* fpa)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(inCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(fpa);

    return(psPlaneDistortApply(outCoord, fpa->toTangentPlane, inCoord,
                               color, magnitude));
}

/*****************************************************************************
XXX: What about units for the (x,y) coords?
 *****************************************************************************/
psSphere* psCoordTPToSky(psSphere* outSphere,
                         const psPlane* tpCoord,
                         const psGrommit* grommit)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(tpCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(grommit);

    double AOB = 0.0;
    double ZOB = 0.0;
    double HOB = 0.0;
    if (outSphere == NULL) {
        outSphere = (psSphere* ) psAlloc(sizeof(psSphere));
    }

    slaAopqk(tpCoord->x, tpCoord->y, (double*)grommit,
             &AOB, &ZOB, &HOB, &outSphere->r, &outSphere->d);

    return (outSphere);
}

psPlane* psCoordCellToFPA(psPlane* fpaCoord,
                          const psPlane* cellCoord,
                          const psCell* cell)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(cellCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(cell);

    return (psPlaneTransformApply(fpaCoord, cell->toFPA, cellCoord));
}

psSphere* psCoordCellToSky(psSphere* skyCoord,
                           const psPlane* cellCoord,
                           double color,
                           double magnitude,
                           const psCell* cell)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(cellCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(cell);

    psPlane* fpaCoord = NULL;
    psPlane* tpCoord = NULL;
    psFPA* parFPA = (cell->parent)->parent;
    psGrommit* tmpGrommit = NULL;

    // Convert the input cell coordinates to FPA coordinates.
    fpaCoord = psPlaneTransformApply(fpaCoord, cell->toFPA, cellCoord);

    // Convert the FPA coordinates to tangent plane Coordinates.
    tpCoord = psPlaneDistortApply(tpCoord, parFPA->toTangentPlane,
                                  fpaCoord, color, magnitude);

    // Generate a grommit for this FPA.
    tmpGrommit = psGrommitAlloc(parFPA->exposure);

    // Convert the tangent plane Coordinates to sky coordinates.
    skyCoord = psCoordTPToSky(skyCoord, tpCoord, tmpGrommit);

    psFree(fpaCoord);
    psFree(tpCoord);
    psFree(tmpGrommit);

    return(skyCoord);
}

psSphere* psCoordCellToSkyQuick(psSphere* outSphere,
                                const psPlane* cellCoord,
                                const psCell* cell)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(cellCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(cell);

    psPlane *tpCoord = NULL;
    psChip *chip = cell->parent;
    psFPA *FPA = chip->parent;
    psProjectionType oldProjectionType;

    if (outSphere == NULL) {
        outSphere = (psSphere* ) psAlloc(sizeof(psSphere));
    }

    // Determine the tangent plane coordinates.
    tpCoord = psPlaneTransformApply(tpCoord, cell->toTP, cellCoord);

    // Save the old projection type and set the new projection type to TAN.
    oldProjectionType = FPA->projection->type;
    FPA->projection->type = PS_PROJ_TAN;

    // Deproject the tangent plane coordinates a sphere.
    outSphere = psDeproject(tpCoord, FPA->projection);

    // Restore old projection type.  Free memory.
    FPA->projection->type = oldProjectionType;
    psFree(tpCoord);

    return (outSphere);
}

/*****************************************************************************
XXX: What about units for the (x,y) coords?
 *****************************************************************************/
psPlane* psCoordSkyToTP(psPlane* tpCoord,
                        const psSphere* in,
                        const psGrommit* grommit)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(in);
    PS_CHECK_NULL_PTR_RETURN_NULL(grommit);

    char* type = "RA";

    if (tpCoord == NULL) {
        tpCoord = (psPlane* ) psAlloc(sizeof(psPlane));
    }

    slaOapqk(type, in->r, in->d, (double*)grommit, &tpCoord->x, &tpCoord->y);

    return(tpCoord);
}


psPlane* psCoordTPToFPA(psPlane* fpaCoord,
                        const psPlane* tpCoord,
                        double color,
                        double magnitude,
                        const psFPA* fpa)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(tpCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(fpa);

    return (psPlaneDistortApply(fpaCoord, fpa->fromTangentPlane,
                                tpCoord, color, magnitude));
}

psPlane* psCoordFPAToChip(psPlane* chipCoord,
                          const psPlane* fpaCoord,
                          const psChip* chip)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(fpaCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(chip);
    PS_CHECK_NULL_PTR_RETURN_NULL(chip->parent);

    chipCoord = psPlaneTransformApply(chipCoord, chip->fromFPA, fpaCoord);
    return(chipCoord);
}

psPlane* psCoordChipToCell(psPlane* cellCoord,
                           const psPlane* chipCoord,
                           const psCell* cell)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(chipCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(cell);
    PS_CHECK_NULL_PTR_RETURN_NULL(cell->parent);

    cellCoord = psPlaneTransformApply(cellCoord, cell->fromChip, chipCoord);
    return(cellCoord);
}

psPlane* psCoordSkyToCell(psPlane* cellCoord,
                          const psSphere* skyCoord,
                          double color,
                          double magnitude,
                          const psCell* cell)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(skyCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(cell);

    psChip *parChip = cell->parent;
    psFPA *parFPA = parChip->parent;
    psGrommit* grommit = parFPA->grommit;

    // Convert the skyCoords to tangent plane coords.
    psPlane *tpCoord = psCoordSkyToTP(tpCoord, skyCoord, grommit);

    // Convert the tangent plane coords to FPA coords.
    psPlane *fpaCoord = psCoordTPToFPA(fpaCoord, tpCoord, color,
                                       magnitude, parFPA);

    // Convert the FPA coords to chip coords.
    psPlane *chipCoord = psCoordFPAToChip(chipCoord, fpaCoord, parChip);

    // Convert the chip coords to cell coords.
    cellCoord = psCoordChipToCell(cellCoord, chipCoord, cell);

    psFree(tpCoord);
    psFree(fpaCoord);
    psFree(chipCoord);

    return (cellCoord);
}

psPlane* psCoordSkyToCellQuick(psPlane* cellCoord,
                               const psSphere* skyCoord,
                               const psCell* cell)
{
    PS_CHECK_NULL_PTR_RETURN_NULL(skyCoord);
    PS_CHECK_NULL_PTR_RETURN_NULL(cell);

    psPlane *tpCoord = NULL;
    psChip *whichChip = cell->parent;
    psFPA *whichFPA = whichChip->parent;
    psProjectionType oldProjectionType;
    psPlaneTransform *TPtoCell = NULL;

    // Save the old projection type and set the new projection type to TAN.
    oldProjectionType = whichFPA->projection->type;
    whichFPA->projection->type = PS_PROJ_TAN;

    if (cellCoord == NULL) {
        cellCoord = (psPlane* ) psAlloc(sizeof(psPlane));
    }

    tpCoord = psProject(skyCoord, whichFPA->projection);

    // generate an error if cell->toTP is not linear.
    if (0 == isProjectionLinear(cell->toTP)) {
        psAbort(__func__, "the cell->toTP transfrom is not linear.\n");
    }

    TPtoCell = invertPlaneTransform(cell->toTP);
    cellCoord = psPlaneTransformApply(cellCoord, TPtoCell, tpCoord);

    // Restore old projection type.  Free memory.
    whichFPA->projection->type = oldProjectionType;
    psFree(tpCoord);
    return (cellCoord);
}

