casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Stokes.h
Go to the documentation of this file.
00001 //# Stokes.h: Stokes parameter definitions for interface to table data
00002 //# Copyright (C) 1994,1995,1996,1997,2000
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: Stokes.h 21130 2011-10-18 07:39:05Z gervandiepen $
00027 
00028 #ifndef MEASURES_STOKES_H
00029 #define MEASURES_STOKES_H
00030 
00031 #include <casa/aips.h>
00032 #include <casa/BasicSL/String.h>
00033 #include <casa/Utilities/Fallible.h>
00034 #include <casa/Arrays/Vector.h>
00035 
00036 namespace casa { //# NAMESPACE CASA - BEGIN
00037 
00038 // <summary>
00039 // Stokes parameter definitions for interface to table data.
00040 // </summary>
00041 
00042 // <reviewed tests="tStokes">
00043 // </reviewed>
00044 
00045 // <synopsis>
00046 // This enumerates the available Stokes types, but does not define
00047 // the operations for conversion between Stokes types.
00048 // This class is a wrapper for the ENUM and conversion functions.
00049 // </synopsis>
00050 
00051 class Stokes {
00052 public:
00053 
00054 // The Stokes types are defined by this enum.
00055 //
00056 // <note role=warning>
00057 // <b>DO NOT CHANGE THE ORDER OF THESE TYPES</b>, as the integers corresponding
00058 // to the <src>enum</src> are required for storage in Tables.
00059 // One can add to these types, but the order must be preserved.
00060 // The correlation products are required to have the order indicated with
00061 // values of 1,2,3,4 plus n*4.
00062 // </note>
00063 //
00064 //# The enum comments below are placed in the position they are to make the
00065 //# extracted documentation look nice.
00066         enum StokesTypes { 
00067             // undefined value = 0
00068             Undefined=0, 
00069             I,  
00070             Q,  
00071             U,  
00072             // standard stokes parameters 
00073             V,
00074             //
00075             RR, 
00076             RL, 
00077             LR, 
00078             // circular correlation products
00079             LL,
00080             //
00081             XX, 
00082             XY, 
00083             YX, 
00084             // linear correlation products
00085             YY,
00086             //
00087             RX, 
00088             RY, 
00089             LX, 
00090             LY,
00091             XR, 
00092             XL, 
00093             YR, 
00094             // mixed correlation products
00095             YL,
00096             //
00097             PP, 
00098             PQ, 
00099             QP, 
00100             // general quasi-orthogonal correlation products
00101             QQ, 
00102             //
00103             RCircular, 
00104             LCircular, 
00105             // single dish polarization types
00106             Linear,
00107             // Polarized intensity ((Q^2+U^2+V^2)^(1/2))
00108             Ptotal,
00109             // Linearly Polarized intensity ((Q^2+U^2)^(1/2))
00110             Plinear,
00111             // Polarization Fraction (Ptotal/I)
00112             PFtotal,
00113             // Linear Polarization Fraction (Plinear/I)
00114             PFlinear,
00115             // Linear Polarization Angle (0.5 arctan(U/Q)) (in radians)
00116             Pangle
00117         };
00118 
00119 //      The number of StokesTypes.
00120 // <note role=warning>
00121 // <b>Update</b> <src>NumberOfTypes</src> when entries are added.
00122 // </note>
00123         enum {
00124             // The number of StokesTypes.
00125             NumberOfTypes = 33
00126             };
00127         
00128 //              convert Int to StokesTypes, returns Stokes::Undefined if 
00129 //              it is an invalid type
00130         static StokesTypes type(Int stokesNumber);
00131 
00132 //              convert String to StokesTypes, returns Stokes::Undefined if
00133 //              it is an unrecognized string.  The valid strings are the
00134 //              same as the characters used in the enum above (i.e.
00135 //              "I" returns Stokes::I, "Linear" returns Stokes::Linear, etc).
00136         static StokesTypes type(const String & stokesName);
00137 
00138 //              convert StokesTypes to String, Stokes::Undefined returns
00139 //              "??".
00140         static String name(StokesTypes stokesType);
00141 
00142         // get all recognized stokes names in no guaranteed order.
00143         static Vector<String> allNames(Bool includeUndefined = False);
00144 
00145 //              map StokesTypes to receptor number (0 or 1) for the
00146 //              interferometric correlation products.
00147 //              e.g. XY will give receptor1==0 receptor2==1 etc.
00148 //              I,Q,U,V and the single dish types will produce invalid
00149 //              Fallible.
00150 //              <group>
00151         static Fallible<Int> receptor1(StokesTypes stokesType);
00152         static Fallible<Int> receptor2(StokesTypes stokesType);
00153 //              </group>
00154 
00155     // These two functions map stokes type to FITS type and vice versa. If you add a 
00156     // StokesType you should change these functions as well.
00157     // <ul>
00158     //     <li> I,Q,U,V <-> 1,2,3,4
00159     //     <li> RR,LL,RL,LR <-> -1,-2,-3,-4   Note! Not the same as enum order!
00160     //     <li> XX,YY,XY,YX <-> -5,-6,-7,-8   Note! Not the same as enum order!
00161     //     <li> Otherwise, FITS type <-> 100 + Int(stokesType). This is not standard FITS.
00162     // </ul>
00163     // <group>
00164         static Int    FITSValue(StokesTypes which);
00165         static StokesTypes fromFITSValue(Int);
00166     // </group>
00167 private:
00168 };
00169 
00170 
00171 } //# NAMESPACE CASA - END
00172 
00173 #endif
00174