Package nom.tam.fits.header

Enum Stokes

java.lang.Object

java.lang.Enum<Stokes>

nom.tam.fits.header.Stokes

All Implemented Interfaces:

Serializable, Comparable<Stokes>, java.lang.constant.Constable

public enum Stokes
extends Enum<Stokes>

A mapping of image coordinate values for a coordinate axis with WCS.CTYPEna = 'STOKES' (or equivalent), specifying polarization (or cross-polarization) data products along the image direction. The FITS standard (4.0) defines a mapping of pixel coordinate values along an image imension to Stokes parameters, and this enum provides an implementation of that for this library.

An dataset may typically contain 4 or 8 Stokes parameters (or fewer), which depending on the type of measurement can be (I, Q, U, [V]), or (RR, LL, RL, LR) and/or (XX, YY, XY, YX). As such, the corresponding WCS.CRPIXna is typically 0 and WCS.CDELTna is +/- 1, and depending on the type of measurement WCS.CRVALna is 1, or -1, or -5. You can use the Stokes.Parameters subclass to help populate or interpret Stokes parameters in headers.

Since:

1.20

Author:

Attila Kovacs

See Also:

• WCS
• parameters()

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	Stokes.Parameters	Helper class for setting or interpreting a set of measured Stokes parameters stored along an array dimension.

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
I	Stokes I: total (polarized + unpolarized) power
LL	circular cross-polarization between two left-handed wave components
LR	circular cross-polarization between a left-handled (input 1) and a right-handed (input 2) wave component
Q	Stokes Q: linear polarization Q component
RL	circular cross-polarization between a right-handled (input 1) and a left-handed (input 2) wave component
RR	circular cross-polarization between two right-handed wave components
U	Stokes U: linear polarization U component
V	Stokes V: circularly polarization
XX	linear cross-polarization between two 'horizontal' wave components (in local orientation)
XY	linear cross-polarization between a 'horizontal' (input 1) and a 'vertical' (input 2) wave component (in local orientation)
YX	linear cross-polarization between a 'vertical' (input 1) and a 'horizontal' (input 2) wave component (in local orientation)
YY	linear cross-polarization between two 'vertical' wave components (in local orientation)

Field Summary

Fields

Modifier and Type	Field	Description
static final int	CIRCULAR_CROSS_POLARIZATION	Bitwise flag for dual-input circular cross polarization Stokes parameters (RR, LL, RL, LR)
static final String	CTYPE	The value to use for CTYPE type keywords to indicate Stokes parameter data
static final int	FULL_CROSS_POLARIZATION	Bitwise flag for dual-input full (linear + circular) cross polarization Stokes parameters (RR, LL, RL, LR, XX, YY, XY, YX).
static final int	LINEAR_CROSS_POLARIZATION	Bitwise flag for dual-input linear cross polarization Stokes parameters (XX, YY, XY, YX)

Method Summary

Modifier and Type	Method	Description
static Stokes	forCoordinateValue(int value)	Returns the Stokes parameter for the given pixel coordinate value for an image coordinate with WCS.CTYPEna = 'STOKES'.
static Map.Entry<Integer,Stokes.Parameters>	fromImageHeader(Header header)	Returns a mapping of a Java array dimension to a set of Stokes parameters, based on the WCS coordinate description in the image header.
static Map.Entry<Integer,Stokes.Parameters>	fromTableHeader(Header header, int column)	Returns a mapping of a Java array dimension to a set of Stokes parameters, based on the WCS coordinate description in the image header.
final int	getCoordinateValue()	Returns the WCS coordinate value corresponding to this Stokes parameter for an image coordinate with WCS.CTYPEna = 'STOKES'.
static Stokes.Parameters	parameters()	Returns a new set of standard single-input Stokes parameters (I, Q, U, V).
static Stokes.Parameters	parameters(int flags)	Returns the set of Stokes parameters for the given bitwise flags, which may specify linear or cicular cross polarization, or both, and/or if the parameters are stored in reversed index order in the FITS.
static Stokes	valueOf(String name)	Returns the enum constant of this type with the specified name.
static Stokes[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

compareTo, describeConstable, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

I

public static final Stokes I

Stokes I: total (polarized + unpolarized) power

Q

public static final Stokes Q

Stokes Q: linear polarization Q component

U

public static final Stokes U

Stokes U: linear polarization U component

V

public static final Stokes V

Stokes V: circularly polarization

RR

public static final Stokes RR

circular cross-polarization between two right-handed wave components

LL

public static final Stokes LL

circular cross-polarization between two left-handed wave components

RL

public static final Stokes RL

circular cross-polarization between a right-handled (input 1) and a left-handed (input 2) wave component

LR

public static final Stokes LR

circular cross-polarization between a left-handled (input 1) and a right-handed (input 2) wave component

XX

public static final Stokes XX

linear cross-polarization between two 'horizontal' wave components (in local orientation)

YY

public static final Stokes YY

linear cross-polarization between two 'vertical' wave components (in local orientation)

XY

public static final Stokes XY

linear cross-polarization between a 'horizontal' (input 1) and a 'vertical' (input 2) wave component (in local orientation)

YX

public static final Stokes YX

linear cross-polarization between a 'vertical' (input 1) and a 'horizontal' (input 2) wave component (in local orientation)

Field Details

CTYPE

public static final String CTYPE

The value to use for CTYPE type keywords to indicate Stokes parameter data

See Also:

• Constant Field Values

LINEAR_CROSS_POLARIZATION

public static final int LINEAR_CROSS_POLARIZATION

Bitwise flag for dual-input linear cross polarization Stokes parameters (XX, YY, XY, YX)

See Also:

• Constant Field Values

CIRCULAR_CROSS_POLARIZATION

public static final int CIRCULAR_CROSS_POLARIZATION

Bitwise flag for dual-input circular cross polarization Stokes parameters (RR, LL, RL, LR)

See Also:

• Constant Field Values

FULL_CROSS_POLARIZATION

public static final int FULL_CROSS_POLARIZATION

Bitwise flag for dual-input full (linear + circular) cross polarization Stokes parameters (RR, LL, RL, LR, XX, YY, XY, YX). By definition tme as (CIRCULAR_CROSS_POLARIZATION | LINEAR_CROSS_POLARIZATION).

See Also:

• CIRCULAR_CROSS_POLARIZATION
• LINEAR_CROSS_POLARIZATION
• Constant Field Values

Method Details

values

public static Stokes[] values()

Returns an array containing the constants of this enum type, in the order they are declared.

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static Stokes valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

getCoordinateValue

public final int getCoordinateValue()

Returns the WCS coordinate value corresponding to this Stokes parameter for an image coordinate with WCS.CTYPEna = 'STOKES'.

Returns:

the WCS coordinate value corresponding to this Stokes parameter.

See Also:

• forCoordinateValue(int)
• WCS.CTYPEna
• WCS.CRVALna

forCoordinateValue

public static Stokes forCoordinateValue(int value)
                                 throws IndexOutOfBoundsException

Returns the Stokes parameter for the given pixel coordinate value for an image coordinate with WCS.CTYPEna = 'STOKES'.

Parameters:

value - The image coordinate value

Returns:

The Stokes parameter, which corresponds to that coordinate value.

Throws:

IndexOutOfBoundsException - if the coordinate value is outt of the range of acceptable Stokes coordinate values.

See Also:

• getCoordinateValue()

parameters

public static Stokes.Parameters parameters()

Returns a new set of standard single-input Stokes parameters (I, Q, U, V).

Returns:

the standard set of I, Q, U, V Stokes parameters.

See Also:

• parameters(int)

parameters

public static Stokes.Parameters parameters(int flags)

Returns the set of Stokes parameters for the given bitwise flags, which may specify linear or cicular cross polarization, or both, and/or if the parameters are stored in reversed index order in the FITS. The flags can be bitwise OR'd, e.g. LINEAR_CROSS_POLARIZATION | CIRCULAR_CROSS_POLARIZATION will select Stokes parameters for measuring circular cross polarization, stored in reversed index order that is: (LR, RL, LL, RR).

Parameters:

flags - the bitwise flags specifying the type of Stokes parameters.

Returns:

the set of Stokes parameters for the given bitwise flags.

See Also:

• parameters()
• LINEAR_CROSS_POLARIZATION
• CIRCULAR_CROSS_POLARIZATION
• FULL_CROSS_POLARIZATION

fromImageHeader

public static Map.Entry<Integer,Stokes.Parameters> fromImageHeader(Header header)
                                                            throws FitsException

Returns a mapping of a Java array dimension to a set of Stokes parameters, based on the WCS coordinate description in the image header. The header must already contain a NAXIS keyword specifying the dimensionality of the data, or else a FitsException will be thrown.

Parameters:

header - the FITS header to populate (it must already have an NAXIS keyword present).

Returns:

A mapping from a zero-based Java array dimension which corresponds to the Stokes dimension of the data, to the set of stokes Parameters defined in that dimension; or null if the header does not contain a fully valid description of a Stokes coordinate axis.

Throws:

FitsException - if the header does not contain an NAXIS keyword, necessary for translating Java array indices to FITS array indices, or if the CRVALn, CRPIXna or CDELTna values for the 'STOKES' dimension are inconsistent with a Stokes coordinate definition.

Since:

1.20

See Also:

• fromTableHeader(Header, int)
• Stokes.Parameters.fillImageHeader(Header, int)

fromTableHeader

public static Map.Entry<Integer,Stokes.Parameters> fromTableHeader(Header header,
 int column)
                                                            throws IndexOutOfBoundsException,
FitsException

Returns a mapping of a Java array dimension to a set of Stokes parameters, based on the WCS coordinate description in the image header.

Parameters:

header - the FITS header to populate.

column - the zero-based Java column index containing the 'image' array.

Returns:

A mapping from a zero-based Java array dimension which corresponds to the Stokes dimension of the data, to the set of stokes Parameters defined in that dimension; or null if the header does not contain a fully valid description of a Stokes coordinate axis.

Throws:

IndexOutOfBoundsException - if the column index is invalid.

FitsException - if the header does not contain an TDIMn keyword for the column, necessary for translating Java array indices to FITS array indices, or if the iCRVLn, iCRPXn or iCDLTn values for the 'STOKES' dimension are inconsistent with a Stokes coordinate definition.

Since:

1.20

See Also:

• fromImageHeader(Header)
• Stokes.Parameters.fillTableHeader(Header, int, int)