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: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef COORDINATES_PROJECTION_H
#define COORDINATES_PROJECTION_H
 
#include <casacore/casa/aips.h>
#include <casacore/casa/Arrays/Vector.h>
#include <casacore/casa/BasicSL/String.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
 
#endif