casacore
FITSCoordinateUtil.h
Go to the documentation of this file.
1 //# FITSCoordinateUtil.h: functions to inter-convert between CoordinateSystems and FITS
2 //# Copyright (C) 1997,1998,1999,2000,2001,2002,2003,2004
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //#
27 //# $Id:
28 
29 #ifndef COORDINATES_FITSCOORDINATEUTIL_H
30 #define COORDINATES_FITSCOORDINATEUTIL_H
31 
32 #include <casacore/casa/aips.h>
33 #include <casacore/measures/Measures/MDirection.h>
34 #include <casacore/measures/Measures/MFrequency.h>
35 #include <casacore/coordinates/Coordinates/ObsInfo.h>
36 
37 
38 struct wcsprm;
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 class Coordinate;
43 class CoordinateSystem;
44 class StokesCoordinate;
45 class Projection;
46 class IPosition;
47 class LogIO;
48 class Record;
49 
50 
51 
52 
53 // <summary>
54 // </summary>
55 
56 // <use visibility=export>
57 
58 // <reviewed reviewer="" date="" tests="">
59 // </reviewed>
60 //
61 // <prerequisite>
62 // <li> <linkto class=Coordinate>CoordinateSystem</linkto>
63 // </prerequisite>
64 
65 // <synopsis>
66 // Helper functions to inter-converft between a CoordinateSystem and FITS
67 // headers.
68 // </synopsis>
69 
70 // <note role=caution>
71 // </note>
72 
73 // <example>
74 // </example>
75 
76 // <motivation>
77 // I hate FITS
78 // </motivation>
79 //
80 // <thrown>
81 // <li> AipsError
82 // </thrown>
83 //
84 // <todo asof="2004/08/23">
85 // </todo>
86 //
87 
88 
90 {
91 public:
92 
93  // Constructor
95 
96  // Convert CoordinateSystem to a FITS header. In the record
97  // the keywords are vectors, it is expected that the actual FITS code will
98  // split them into scalars and upcase the names. Returns False if one of the
99  // keywords is already taken.
100  //
101  // If writeWCS is True, attempt to write the WCS convention (Greisen and
102  // Calabretta "Representation of celestial coordinates in FITS") as
103  // approved in version 3.0 of the FITS standard.
104  // Use <src>oneRelative=True</src> to convert zero-relative pixel coordinates to
105  // one-relative FITS coordinates.
106  //
107  // prefix gives the prefix for the FITS keywords. E.g.,
108  // if prefix="c" then crval, cdelt etc.
109  // if prefix="d" then drval, ddelt etc.
110  //# Much of the work in to/from fits should be moved to the individual
111  //# classes.
113  IPosition &shape,
114  const CoordinateSystem& cSys,
115  Bool oneRelative,
116  Char prefix = 'c', Bool writeWCS=True,
117  Bool preferVelocity=True,
118  Bool opticalVelocity=True,
119  Bool preferWavelength=False,
120  Bool airWavelength=False) const;
121 
122  // Probably even if we return False we should set up the best linear
123  // coordinate that we can. On output, <src>stokesFITSValue</src>
124  // holds the FITS value of any unofficial Stokes (beam, optical depth,
125  // spectral index) for the last unofficial value accessed (-1 if none).
126  // The idea is that if the Stokes axis is of length one and holds an unofficial value,
127  // you should drop the STokes axis and convert that value to <src>ImageInfo::ImageTypes</src>
128  // with <src>ImageInfo::imageTypeFromFITSValue</src>. If on input, <src>stokesFITSValue</src>
129  // is positive, then a warning is issued if any unofficial values are encountered.
130  // Otherwise no warning is issued.
131  //# cf comment in toFITS.
132  //<group>
133  Bool fromFITSHeader(Int& stokesFITSValue,
134  CoordinateSystem& coordsys,
135  RecordInterface& recHeader,
136  const Vector<String>& header,
137  const IPosition& shape,
138  uInt which=0) const;
139  //</group>
140 
141 
142  // Helper function to create a FITS style CTYPE vector from the
143  // axis names from a DirectionCoordinate
144  static Vector<String> cTypeFromDirection (Bool& isNCP, const Projection& proj,
145  const Vector<String>& axisNames,
146  Double refLat, Bool printError);
148  const Vector<String>& axisNames,
149  Bool printError);
150 
151 private:
152  // Generate actual FITS keywords
154  Double& longPole, Double& latPole,
155  Vector<Double>& crval,
156  Vector<Double>& crpix,
157  Vector<Double>& cdelt,
158  //# Vector<Double>& crota,
159  //# Vector<Double>& projp,
160  Vector<Double>& pvi_ma,
161  Vector<String>& ctype,
162  Vector<String>& cunit,
163  Matrix<Double>& pc,
164  const CoordinateSystem& cSys,
165  Int skyCoord, Int longAxis, Int latAxis,
166  Int specAxis, Int stokesAxis,
167  Bool writeWCS, Double offset,
168  const String& sprefix) const;
169 
170  // Special Stokes processing for conversion to FITS header
172  Vector<Double>& crpix,
173  Vector<Double>& cdelt,
174  LogIO& os,
175  const CoordinateSystem& coordsys,
176  Int stokesAxis, Int stokesCoord) const;
177 
178  // Look for Coordinate type and add to CS
179  // <group>
181  const wcsprm& wcs, LogIO& os) const;
183  const wcsprm& wcs, const IPosition& shape,
184  LogIO& os) const;
185  Bool addStokesCoordinate (CoordinateSystem& cSys, Int& axis, Int& stokesFITSValue,
186  const wcsprm& wcs, const IPosition& shape,
187  LogIO& os) const;
189  const wcsprm& wcs, LogIO& os) const;
190  // </group>
191 
192 // Decode values from WCS structures which are generated via the wcs FITS parser
193  // <group>
195  const wcsprm& wcs) const;
197  const wcsprm& wcs) const;
199  Int& stokesFITSValue, String& errMSg,
200  const wcsprm& wcs, uInt shape, Bool warnStokes) const;
201  // </group>
202 
203  // Decode ObsInfo from wcs structure
204  ObsInfo getObsInfo(LogIO& os, RecordInterface& header, const wcsprm& wcs) const;
205 
206  // Call wcsset
207  void setWCS (wcsprm& wcs) const;
208 
209  // Decode CD cards from FITS file header (Record interface)
211 
212  // Decode PC matrix from FITS header (Record interface)
213  void getPCFromHeader(LogIO& os, Int& rotationAxis, Matrix<Double>& pc,
214  uInt n, const RecordInterface& header,
215  const String& sprefix);
216 
217  // Helper function to convert a wcs structure holding FITS keywords
218  // into a Record for later consumption.
219  void cardsToRecord (LogIO& os, RecordInterface& rec, char* pHeader) const;
220 
221  // Fix up Coordinate for zero increments and the like
222  // Possibly the wcs FITS parser could do this
223  void fixCoordinate(Coordinate& c, LogIO& os) const;
224 
225  // Initialize the wcsprm struct.
226  // It sets the flag to -1, but furthermore it clears the err pointers
227  // because wcslib-4.8 (shipped with Ubuntu) sometimes fails to do so.
228  static void wcsInit (::wcsprm& wcsDest);
229 };
230 
231 } //# NAMESPACE CASACORE - END
232 
233 #endif
234 
ObsInfo getObsInfo(LogIO &os, RecordInterface &header, const wcsprm &wcs) const
Decode ObsInfo from wcs structure.
static void wcsInit(::wcsprm &wcsDest)
Initialize the wcsprm struct.
Bool fromFITSHeader(Int &stokesFITSValue, CoordinateSystem &coordsys, RecordInterface &recHeader, const Vector< String > &header, const IPosition &shape, uInt which=0) const
Probably even if we return False we should set up the best linear coordinate that we can.
void fixCoordinate(Coordinate &c, LogIO &os) const
Fix up Coordinate for zero increments and the like Possibly the wcs FITS parser could do this.
static Vector< String > cTypeFromDirection(const Projection &proj, const Vector< String > &axisNames, Bool printError)
Bool addStokesCoordinate(CoordinateSystem &cSys, Int &axis, Int &stokesFITSValue, const wcsprm &wcs, const IPosition &shape, LogIO &os) const
void getPCFromHeader(LogIO &os, Int &rotationAxis, Matrix< Double > &pc, uInt n, const RecordInterface &header, const String &sprefix)
Decode PC matrix from FITS header (Record interface)
void cardsToRecord(LogIO &os, RecordInterface &rec, char *pHeader) const
Helper function to convert a wcs structure holding FITS keywords into a Record for later consumption.
Bool addDirectionCoordinate(CoordinateSystem &cSys, Vector< Int > &axes, const wcsprm &wcs, LogIO &os) const
Look for Coordinate type and add to CS.
void setWCS(wcsprm &wcs) const
Call wcsset.
static Vector< String > cTypeFromDirection(Bool &isNCP, const Projection &proj, const Vector< String > &axisNames, Double refLat, Bool printError)
Helper function to create a FITS style CTYPE vector from the axis names from a DirectionCoordinate.
Bool toFITSHeader(RecordInterface &header, IPosition &shape, const CoordinateSystem &cSys, Bool oneRelative, Char prefix='c', Bool writeWCS=True, Bool preferVelocity=True, Bool opticalVelocity=True, Bool preferWavelength=False, Bool airWavelength=False) const
Convert CoordinateSystem to a FITS header.
Bool stokesCoordinateFromWCS(LogIO &os, StokesCoordinate &coord, Int &stokesFITSValue, String &errMSg, const wcsprm &wcs, uInt shape, Bool warnStokes) const
Bool addLinearCoordinate(CoordinateSystem &cSys, Vector< Int > &axes, const wcsprm &wcs, LogIO &os) const
Bool toFITSHeaderStokes(Vector< Double > &crval, Vector< Double > &crpix, Vector< Double > &cdelt, LogIO &os, const CoordinateSystem &coordsys, Int stokesAxis, Int stokesCoord) const
Special Stokes processing for conversion to FITS header.
Bool addSpectralCoordinate(CoordinateSystem &cSys, Int &axis, const wcsprm &wcs, const IPosition &shape, LogIO &os) const
Bool generateFITSKeywords(LogIO &os, Bool &isNCP, Double &longPole, Double &latPole, Vector< Double > &crval, Vector< Double > &crpix, Vector< Double > &cdelt, Vector< Double > &pvi_ma, Vector< String > &ctype, Vector< String > &cunit, Matrix< Double > &pc, const CoordinateSystem &cSys, Int skyCoord, Int longAxis, Int latAxis, Int specAxis, Int stokesAxis, Bool writeWCS, Double offset, const String &sprefix) const
Generate actual FITS keywords.
Bool frequencySystemFromWCS(LogIO &os, MFrequency::Types &type, String &errMsg, const wcsprm &wcs) const
Bool getCDFromHeader(Matrix< Double > &cd, uInt n, const RecordInterface &header)
Decode CD cards from FITS file header (Record interface)
Bool directionSystemFromWCS(LogIO &os, MDirection::Types &type, String &errMsg, const wcsprm &wcs) const
Decode values from WCS structures which are generated via the wcs FITS parser.
Types
Types of known MDirections Warning: The order defines the order in the translation matrix FromTo in ...
Definition: MDirection.h:188
Types
Types of known MFrequencies Warning: The order defines the order in the translation matrix FromTo in...
Definition: MFrequency.h:176
String: the storage and methods of handling collections of characters.
Definition: String.h:225
const Double c
Fundamental physical constants (SI units):
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1987
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55
char Char
Definition: aipstype.h:46