Projection.h

Go to the documentation of this file.

//# Projection.h: Geometric parameters needed for a sky projection to a plane
//# Copyright (C) 1997,1998,1999,2000,2001,2003
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//#
//# $Id$

#ifndef COORDINATES_PROJECTION_H
#define COORDINATES_PROJECTION_H

#include <casacore/casa/aips.h>
#include <casacore/casa/Arrays/Vector.h>

namespace casacore { //# NAMESPACE CASACORE - BEGIN


// <summary>
//  Geometric parameters needed for a sky projection to a plane
// </summary>

// <use visibility=export>

// <reviewed reviewer="Peter Barnes" date="1999/12/24" tests="tProjection">
// </reviewed>
//
// <prerequisite>
//   <li> Knowledge of astronomical coordinate conversions in general. Probably the
//        best documents are the papers by Mark Calabretta and Eric Greisen.
//        The initial draft from 1996 can be found at
//        http://www.atnf.csiro.au/~mcalabre.  It is this draft that the
//        Coordinate classes are based upon.  Since then, this paper has evolved
//        into three which can be found at the above address, and will be published in the
//        Astronomy and Astrophysics Supplement Series (probably in 2000).
//        The design has changed since the initial draft.  When these papers
//        are finalized, and the IAU has ratified the new standards, WCSLIB
//        (Mark Calabretta's implementation of these conventions) will be
//        revised for the new designs.  At that time, the Coordinate classes
//        may also be revised.
// </prerequisite>
//
// <synopsis>
// This class is used to hold:
// <ol>
//    <li> The type of the projection (e.g. SIN); and
//    <li> The parameters of the projection, if any. These parameters are described
//         by Calabretta and Greisen (called PROJP) in the 1996 draft. 
//         In the recent versions, this paper has split into three, and the
//         projection parameters have been reworked into the PV matrix.
//         However, these have not yet been implemented in WCSLIB so we
//         stick with the old ones for now.
// </ol>
// </synopsis>
//
// <example>
// <srcblock>
//    Projection proj(Projection::CAR);
//    cerr << proj.parameters() << endl;
// </srcblock>
// This projection requires no parameters so the printed parameter
// vector would be of zero length.
// </example>
//
// <thrown>
//   <li>  AipsError
// </thrown>
//
// <todo asof="2000/01/01">
//   <li> Worry about projection parameters which are unit dependent (i.e. 
//        radians vs. degrees).
//   <li> LONGPOLE should probably go in here.
// </todo>
// 

class Projection
{
public:
    // Hold all the known types of celestial projections.
    enum Type {
        // Zenithal/Azimuthal perspective.
        AZP,
        // Slant zenithal perspective, new
        SZP,
        // Gnomonic.
        TAN, 
        // Orthographics/synthesis.
        SIN, 
        // Stereographic.
        STG, 
        // zenith/azimuthal equidistant.
        ARC, 
        // zenithal/azimuthal polynomial.
        ZPN, 
        // zenithal/azimuthal equal area.
        ZEA, 
        // Airy.
        AIR, 
        // Cylindrical perspective.
        CYP, 
        // Plate carree
        CAR, 
        // Mercator.
        MER, 
        // Cylindrical equal area.
        CEA,
        // Conic perspective.
        COP, 
        // Conic equidistant.
        COD, 
        // Conic equal area.
        COE, 
        // Conic orthomorphic.
        COO, 
        // Bonne.
        BON, 
        // Polyconic.
        PCO, 
        // Sanson-Flamsteed (global sinusoidal).
        // The old GLS projection is now SFL. The 'GLS'
        // string will be converted to 'SFL'
        SFL, 
        // Parabolic.
        PAR, 
        // Hammer-Aitoff.
        AIT, 
        // Mollweide.
        MOL, 
        // COBE quadrilateralized spherical cube.
        CSC, 
        // Quadrilateralized spherical cube.
        QSC,
        // Tangential spherical cube.
        TSC,
        // HEALPix grid
        HPX, 
        // N_PROJ gives the number of supported projections - it shouldn't be used
        // as a projection
        N_PROJ };

    // Construct a projection which needs no parameters. SIN is unique in that
    // it can be created with 0 or 2 parameters.
    Projection(Projection::Type which=CAR);

    // Construct a projection from FITS CTYPE keywords
    Projection(const String& ctypeLin, const String& ctypeLat,
               const Vector<Double>& parameters);

    // Construct a projection which needs parameters. The parameter vector must be
    // the length of the required number of parameters.
    Projection(Projection::Type which, const Vector<Double> &parameters);

    // Copy constructor (copy semantics).
    Projection(const Projection &other);

    // Assignment (copy semantics)
    Projection &operator=(const Projection &other);

    // Destructor
    ~Projection();

    // What is the Type of this projection?
    Projection::Type type() const;

    // What is the type of this projection as a String (e.g. "SIN").
    // <group>
    String name() const;
    static String name(Projection::Type proj);
    // </group>

    // Turn a projection type name into a Type. 
    // Returns N_PROJ if the projection is not known.
    static Projection::Type type(const String &name);

    // How many parameters does this projection have at most?
    // What is the minimum number of parameters that have to be supplied?
    // What are the parameter values?
    // <group>
    static uInt nParameters(Projection::Type proj);
    static uInt nMinParameters(Projection::Type proj);
    const Vector<Double> &parameters() const;
    // </group>

    // Comparison to fractional tolerance. 
    Bool near(const Projection &other, Double tol=1.0e-6) const;

    // Is this projection a 'zenithal' projection
    static Bool isZenithal (Projection::Type proj);

private:
    Projection::Type which_p;
    Vector<Double> parameters_p;

    void validate(const Bool verbose=False);
    Projection::Type type (String& ctypeLong, String& ctypeLat) const;
};

//#---------- Inlines --------------------------------------------------------------
inline Projection::Type Projection::type() const {return which_p;}
inline const Vector<Double> & Projection::parameters() const {return parameters_p;}

} //# NAMESPACE CASACORE - END

#endif