1 package nom.tam.fits.header;
2
3 /*-
4 * #%L
5 * nom.tam.fits
6 * %%
7 * Copyright (C) 1996 - 2024 nom-tam-fits
8 * %%
9 * This is free and unencumbered software released into the public domain.
10 *
11 * Anyone is free to copy, modify, publish, use, compile, sell, or
12 * distribute this software, either in source code form or as a compiled
13 * binary, for any purpose, commercial or non-commercial, and by any
14 * means.
15 *
16 * In jurisdictions that recognize copyright laws, the author or authors
17 * of this software dedicate any and all copyright interest in the
18 * software to the public domain. We make this dedication for the benefit
19 * of the public at large and to the detriment of our heirs and
20 * successors. We intend this dedication to be an overt act of
21 * relinquishment in perpetuity of all present and future rights to this
22 * software under copyright law.
23 *
24 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
25 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
26 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
27 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
28 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
29 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
30 * OTHER DEALINGS IN THE SOFTWARE.
31 * #L%
32 */
33
34 import java.util.AbstractMap;
35 import java.util.ArrayList;
36 import java.util.Map;
37 import java.util.StringTokenizer;
38
39 import nom.tam.fits.FitsException;
40 import nom.tam.fits.Header;
41
42 /**
43 * <p>
44 * A mapping of image coordinate values for a coordinate axis with {@link WCS#CTYPEna} = <code>'STOKES'</code> (or
45 * equivalent), specifying polarization (or cross-polarization) data products along the image direction. The FITS
46 * standard (4.0) defines a mapping of pixel coordinate values along an image imension to Stokes parameters, and this
47 * enum provides an implementation of that for this library.
48 * </p>
49 * <p>
50 * An dataset may typically contain 4 or 8 Stokes parameters (or fewer), which depending on the type of measurement can
51 * be (I, Q, U, [V]), or (RR, LL, RL, LR) and/or (XX, YY, XY, YX). As such, the corresponding {@link WCS#CRPIXna} is
52 * typically 0 and {@link WCS#CDELTna} is +/- 1, and depending on the type of measurement {@link WCS#CRVALna} is 1, or
53 * -1, or -5. You can use the {@link Parameters} subclass to help populate or interpret Stokes parameters in headers.
54 * </p>
55 *
56 * @author Attila Kovacs
57 *
58 * @since 1.20
59 *
60 * @see WCS
61 * @see #parameters()
62 */
63 public enum Stokes {
64 /** Stokes I: total (polarized + unpolarized) power */
65 I(1),
66
67 /** Stokes Q: linear polarization Q component */
68 Q(2),
69
70 /** Stokes U: linear polarization U component */
71 U(3),
72
73 /** Stokes V: circularly polarization */
74 V(4),
75
76 /** circular cross-polarization between two right-handed wave components */
77 RR(-1),
78
79 /** circular cross-polarization between two left-handed wave components */
80 LL(-2),
81
82 /** circular cross-polarization between a right-handled (input 1) and a left-handed (input 2) wave component */
83 RL(-3),
84
85 /** circular cross-polarization between a left-handled (input 1) and a right-handed (input 2) wave component */
86 LR(-4),
87
88 /** linear cross-polarization between two 'horizontal' wave components (in local orientation) */
89 XX(-5),
90
91 /** linear cross-polarization between two 'vertical' wave components (in local orientation) */
92 YY(-6),
93
94 /**
95 * linear cross-polarization between a 'horizontal' (input 1) and a 'vertical' (input 2) wave component (in local
96 * orientation)
97 */
98 XY(-7),
99
100 /**
101 * linear cross-polarization between a 'vertical' (input 1) and a 'horizontal' (input 2) wave component (in local
102 * orientation)
103 */
104 YX(-8);
105
106 /** The value to use for CTYPE type keywords to indicate Stokes parameter data */
107 public static final String CTYPE = "STOKES";
108
109 private int index;
110
111 private static Stokes[] ordered = {YX, XY, YY, XX, LR, RL, LL, RR, null, I, Q, U, V};
112
113 private static final int STANDARD_PARAMETER_COUNT = 4;
114 private static final int FULL_PARAMETER_COUNT = 8;
115
116 Stokes(int value) {
117 this.index = value;
118 }
119
120 /**
121 * Returns the WCS coordinate value corresponding to this Stokes parameter for an image coordinate with
122 * {@link WCS#CTYPEna} = <code>'STOKES'</code>.
123 *
124 * @return the WCS coordinate value corresponding to this Stokes parameter.
125 *
126 * @see #forCoordinateValue(int)
127 * @see WCS#CTYPEna
128 * @see WCS#CRVALna
129 */
130 public final int getCoordinateValue() {
131 return index;
132 }
133
134 /**
135 * Returns the Stokes parameter for the given pixel coordinate value for an image coordinate with
136 * {@link WCS#CTYPEna} = <code>'STOKES'</code>.
137 *
138 * @param value The image coordinate value
139 *
140 * @return The Stokes parameter, which corresponds to that coordinate value.
141 *
142 * @throws IndexOutOfBoundsException if the coordinate value is outt of the range of acceptable Stokes coordinate
143 * values.
144 *
145 * @see #getCoordinateValue()
146 */
147 public static Stokes forCoordinateValue(int value) throws IndexOutOfBoundsException {
148 return ordered[value - YX.getCoordinateValue()];
149 }
150
151 /**
152 * Helper class for setting or interpreting a set of measured Stokes parameters stored along an array dimension. Two
153 * instances of Stokes parameters are considered equal if they measure the same polarization terms, in the same
154 * order.
155 *
156 * @author Attila Kovacs
157 *
158 * @since 1.20
159 */
160 public static final class Parameters {
161 private int flags;
162 private int offset;
163 private int step;
164 private int count;
165
166 private Parameters(int flags) {
167 this.flags = flags;
168
169 boolean reversed = (flags & REVERSED_ORDER) != 0;
170
171 step = reversed ? -1 : 1;
172 count = STANDARD_PARAMETER_COUNT;
173
174 if ((flags & FULL_CROSS_POLARIZATION) == 0) {
175 offset = reversed ? Stokes.V.getCoordinateValue() : Stokes.I.getCoordinateValue();
176 } else {
177 step = -step;
178
179 if ((flags & CIRCULAR_CROSS_POLARIZATION) == 0) {
180 offset = reversed ? Stokes.YX.getCoordinateValue() : Stokes.XX.getCoordinateValue();
181 } else if ((flags & LINEAR_CROSS_POLARIZATION) == 0) {
182 offset = reversed ? Stokes.LR.getCoordinateValue() : Stokes.RR.getCoordinateValue();
183 } else {
184 offset = reversed ? Stokes.YX.getCoordinateValue() : Stokes.RR.getCoordinateValue();
185 count = FULL_PARAMETER_COUNT;
186 }
187 }
188 }
189
190 private Parameters(int offset, int step, int n) {
191 this.offset = offset;
192 this.step = step;
193 this.count = n;
194
195 if (offset < 0) {
196 int end = offset + (n - 1) * step;
197
198 if (Math.min(offset, end) <= XX.index) {
199 flags |= LINEAR_CROSS_POLARIZATION;
200 }
201
202 if (Math.max(offset, end) > XX.index) {
203 flags |= CIRCULAR_CROSS_POLARIZATION;
204 }
205
206 step = -step;
207 }
208
209 if (step < 0) {
210 flags |= REVERSED_ORDER;
211 }
212 }
213
214 @Override
215 public int hashCode() {
216 return flags ^ Integer.hashCode(offset) ^ Integer.hashCode(step);
217 }
218
219 @Override
220 public boolean equals(Object o) {
221 if (!(o instanceof Parameters)) {
222 return false;
223 }
224 Parameters p = (Parameters) o;
225 if (p.flags != flags) {
226 return false;
227 }
228 if (p.offset != offset) {
229 return false;
230 }
231 if (p.step != step) {
232 return false;
233 }
234 return true;
235 }
236
237 boolean isReversedOrder() {
238 return (flags & REVERSED_ORDER) != 0;
239 }
240
241 /**
242 * Checks if the parameters are for measuring cross-polarization between two inputs.
243 *
244 * @return <code>true</code> if it is for cross polarization, otherwise <code>false</code>.
245 */
246 public boolean isCrossPolarization() {
247 return (flags & FULL_CROSS_POLARIZATION) != 0;
248 }
249
250 /**
251 * Checks if the parameters include linear polarization terms.
252 *
253 * @return <code>true</code> if linear polarization is measured, otherwise <code>false</code>.
254 */
255 public boolean hasLinearPolarization() {
256 return (flags & FULL_CROSS_POLARIZATION) != CIRCULAR_CROSS_POLARIZATION;
257 }
258
259 /**
260 * Checks if the parameters include circular polarization term(s).
261 *
262 * @return <code>true</code> if cirular cross polarization is measured, otherwise <code>false</code>.
263 */
264 public boolean hasCircularPolarization() {
265 return (flags & FULL_CROSS_POLARIZATION) != LINEAR_CROSS_POLARIZATION;
266 }
267
268 /**
269 * Returns the Stokes parameter for a given Java array index for a dimension that corresponds to the Stokes
270 * parameters described by this instance.
271 *
272 * @param idx the zero-based Java array index, typically [0:3] for single-ended
273 * polarization or circular or linear-only cross-polarization, or else
274 * [0:7] for full cross-polarization.
275 *
276 * @return The specific Stokes parameter corresponding to the specified array index.
277 *
278 * @throws IndexOutOfBoundsException if the index is outside of the expected range.
279 *
280 * @see #getAvailableParameters()
281 *
282 * @since 1.19.1
283 */
284 public Stokes getParameter(int idx) throws IndexOutOfBoundsException {
285 if (idx < 0 || idx >= count) {
286 throw new IndexOutOfBoundsException();
287 }
288 return Stokes.forCoordinateValue(offset + step * idx);
289 }
290
291 /**
292 * Returns the ordered list of parameters, which can be used to translate array indexes to Stokes values,
293 * supported by this parameter set.
294 *
295 * @return the ordered list of available Stokes parameters in this measurement set.
296 *
297 * @see #getParameter(int)
298 */
299 public ArrayList<Stokes> getAvailableParameters() {
300 ArrayList<Stokes> list = new ArrayList<>(count);
301 for (int i = 0; i < count; i++) {
302 list.add(getParameter(i));
303 }
304 return list;
305 }
306
307 /**
308 * Returns the Java array index corresponding to a given Stokes parameters for this set of parameters.
309 *
310 * @param s the Stokes parameter of interest
311 *
312 * @return the zero-based Java array index corresponding to the given Stokes parameter.
313 *
314 * @see #getParameter(int)
315 *
316 * @since 1.20
317 */
318 public int getArrayIndex(Stokes s) {
319 return (s.getCoordinateValue() - offset) / step;
320 }
321
322 /**
323 * Adds WCS description for the coordinate axis containing Stokes parameters. The header must already contain a
324 * NAXIS keyword specifying the dimensionality of the data, or else a FitsException will be thrown.
325 *
326 * @param header the FITS header to populate (it must already have an NAXIS keyword
327 * present).
328 * @param coordinateIndex The 0-based Java coordinate index for the array dimension that corresponds
329 * to the stokes parameter.
330 *
331 * @throws IndexOutOfBoundsException if the coordinate index is negative or out of bounds for the array
332 * dimensions
333 * @throws FitsException if the header does not contain an NAXIS keyword, or if the header is not
334 * accessible
335 *
336 * @see #fillTableHeader(Header, int, int)
337 * @see Stokes#fromImageHeader(Header)
338 *
339 * @since 1.20
340 */
341 public void fillImageHeader(Header header, int coordinateIndex) throws FitsException {
342 int n = header.getIntValue(Standard.NAXIS);
343 if (n == 0) {
344 throw new FitsException("Missing NAXIS in header");
345 }
346 if (coordinateIndex < 0 || coordinateIndex >= n) {
347 throw new IndexOutOfBoundsException(
348 "Invalid Java coordinate index " + coordinateIndex + " (for " + n + " dimensions)");
349 }
350
351 int i = n - coordinateIndex;
352
353 header.addValue(WCS.CTYPEna.n(i), Stokes.CTYPE);
354 header.addValue(WCS.CRPIXna.n(i), 1);
355 header.addValue(WCS.CRVALna.n(i), offset);
356 header.addValue(WCS.CDELTna.n(i), step);
357 }
358
359 /**
360 * Adds WCS description for the coordinate axis containing Stokes parameters to a table column containign
361 * images.
362 *
363 * @param header the binary table header to populate (it should already contain a TDIMn
364 * keyword for the specified column, or else 1D data is assumed).
365 * @param column the zero-based Java column index containing the 'image' array.
366 * @param coordinateIndex the zero-based Java coordinate index for the array dimension that
367 * corresponds to the stokes parameter.
368 *
369 * @throws IndexOutOfBoundsException if the coordinate index is negative or out of bounds for the array
370 * dimensions, or if the column index is invalid.
371 * @throws FitsException if the header does not specify the dimensionality of the array elements, or
372 * if the header is not accessible
373 *
374 * @see #fillImageHeader(Header, int)
375 * @see Stokes#fromTableHeader(Header, int)
376 *
377 * @since 1.20
378 */
379 public void fillTableHeader(Header header, int column, int coordinateIndex)
380 throws IndexOutOfBoundsException, FitsException {
381 if (column < 0) {
382 throw new IndexOutOfBoundsException("Invalid Java column index " + column);
383 }
384
385 String dims = header.getStringValue(Standard.TDIMn.n(++column));
386 if (dims == null) {
387 throw new FitsException("Missing TDIM" + column + " in header");
388 }
389
390 StringTokenizer tokens = new StringTokenizer(dims, "(, )");
391 int n = tokens.countTokens();
392
393 if (coordinateIndex < 0 || coordinateIndex >= n) {
394 throw new IndexOutOfBoundsException(
395 "Invalid Java coordinate index " + coordinateIndex + " (for " + n + " dimensions)");
396 }
397
398 int i = n - coordinateIndex;
399
400 header.addValue(WCS.nCTYPn.n(i, column), Stokes.CTYPE);
401 header.addValue(WCS.nCRPXn.n(i, column), 1);
402 header.addValue(WCS.nCRVLn.n(i, column), offset);
403 header.addValue(WCS.nCDLTn.n(i, column), step);
404 }
405 }
406
407 /**
408 * Returns a new set of standard single-input Stokes parameters (I, Q, U, V).
409 *
410 * @return the standard set of I, Q, U, V Stokes parameters.
411 *
412 * @see #parameters(int)
413 */
414 public static Parameters parameters() {
415 return parameters(0);
416 }
417
418 /**
419 * Returns the set of Stokes parameters for the given bitwise flags, which may specify linear or cicular cross
420 * polarization, or both, and/or if the parameters are stored in reversed index order in the FITS. The flags can be
421 * bitwise OR'd, e.g. {@link #LINEAR_CROSS_POLARIZATION} | {@link #CIRCULAR_CROSS_POLARIZATION} will select Stokes
422 * parameters for measuring circular cross polarization, stored in reversed index order that is: (LR, RL, LL, RR).
423 *
424 * @param flags the bitwise flags specifying the type of Stokes parameters.
425 *
426 * @return the set of Stokes parameters for the given bitwise flags.
427 *
428 * @see #parameters()
429 * @see #LINEAR_CROSS_POLARIZATION
430 * @see #CIRCULAR_CROSS_POLARIZATION
431 * @see #FULL_CROSS_POLARIZATION
432 */
433 public static Parameters parameters(int flags) {
434 return new Parameters(flags);
435 }
436
437 /**
438 * Bitwise flag for Stokes parameters stored in reversed index order.
439 */
440 static final int REVERSED_ORDER = 1;
441
442 /**
443 * Bitwise flag for dual-input linear cross polarization Stokes parameters (XX, YY, XY, YX)
444 */
445 public static final int LINEAR_CROSS_POLARIZATION = 2;
446
447 /**
448 * Bitwise flag for dual-input circular cross polarization Stokes parameters (RR, LL, RL, LR)
449 */
450 public static final int CIRCULAR_CROSS_POLARIZATION = 4;
451
452 /**
453 * Bitwise flag for dual-input full (linear + circular) cross polarization Stokes parameters (RR, LL, RL, LR, XX,
454 * YY, XY, YX). By definition tme as ({@link #CIRCULAR_CROSS_POLARIZATION} | {@link #LINEAR_CROSS_POLARIZATION}).
455 *
456 * @see #CIRCULAR_CROSS_POLARIZATION
457 * @see #LINEAR_CROSS_POLARIZATION
458 */
459 public static final int FULL_CROSS_POLARIZATION = LINEAR_CROSS_POLARIZATION | CIRCULAR_CROSS_POLARIZATION;
460
461 private static Parameters forCoords(double start, double delt, int count) throws FitsException {
462 int offset = (int) start;
463 if (start != offset) {
464 throw new FitsException("Invalid (non-integer) Stokes coordinate start: " + start);
465 }
466
467 int step = (int) delt;
468 if (delt != step) {
469 throw new FitsException("Invalid (non-integer) Stokes coordinate step: " + delt);
470 }
471
472 int end = offset + step * (count - 1);
473 if (Math.min(offset, end) <= 0 && Math.max(offset, end) >= 0) {
474 throw new FitsException("Invalid Stokes coordinate range: " + offset + ":" + end);
475 }
476
477 return new Parameters(offset, step, count);
478 }
479
480 /**
481 * Returns a mapping of a Java array dimension to a set of Stokes parameters, based on the WCS coordinate
482 * description in the image header. The header must already contain a NAXIS keyword specifying the dimensionality of
483 * the data, or else a FitsException will be thrown.
484 *
485 * @param header the FITS header to populate (it must already have an NAXIS keyword present).
486 *
487 * @return A mapping from a zero-based Java array dimension which corresponds to the Stokes dimension
488 * of the data, to the set of stokes Parameters defined in that dimension; or
489 * <code>null</code> if the header does not contain a fully valid description of a Stokes
490 * coordinate axis.
491 *
492 * @throws FitsException if the header does not contain an NAXIS keyword, necessary for translating Java array
493 * indices to FITS array indices, or if the CRVALn, CRPIXna or CDELTna values for the
494 * 'STOKES' dimension are inconsistent with a Stokes coordinate definition.
495 *
496 * @see #fromTableHeader(Header, int)
497 * @see Parameters#fillImageHeader(Header, int)
498 *
499 * @since 1.20
500 */
501 @SuppressWarnings({"unchecked", "rawtypes"})
502 public static Map.Entry<Integer, Parameters> fromImageHeader(Header header) throws FitsException {
503 int n = header.getIntValue(Standard.NAXIS);
504 if (n <= 0) {
505 throw new FitsException("Missing, invalid, or insufficient NAXIS in header");
506 }
507
508 for (int i = 1; i <= n; i++) {
509 if (Stokes.CTYPE.equalsIgnoreCase(header.getStringValue(WCS.CTYPEna.n(i)))) {
510 if (header.getDoubleValue(WCS.CRPIXna.n(i), 1.0) != 1.0) {
511 throw new FitsException("Invalid Stokes " + WCS.CRPIXna.n(i).key() + " value: "
512 + header.getDoubleValue(WCS.CRPIXna.n(i)) + ", expected 1");
513 }
514
515 Parameters p = forCoords(header.getDoubleValue(WCS.CRVALna.n(i), 0.0),
516 header.getDoubleValue(WCS.CDELTna.n(i), 1.0), header.getIntValue(Standard.NAXISn.n(i), 1));
517
518 return new AbstractMap.SimpleImmutableEntry(n - i, p);
519 }
520 }
521
522 return null;
523 }
524
525 /**
526 * Returns a mapping of a Java array dimension to a set of Stokes parameters, based on the WCS coordinate
527 * description in the image header.
528 *
529 * @param header the FITS header to populate.
530 * @param column the zero-based Java column index containing the 'image' array.
531 *
532 * @return A mapping from a zero-based Java array dimension which corresponds to the
533 * Stokes dimension of the data, to the set of stokes Parameters defined in
534 * that dimension; or <code>null</code> if the header does not contain a fully
535 * valid description of a Stokes coordinate axis.
536 *
537 * @throws IndexOutOfBoundsException if the column index is invalid.
538 * @throws FitsException if the header does not contain an TDIMn keyword for the column, necessary for
539 * translating Java array indices to FITS array indices, or if the iCRVLn,
540 * iCRPXn or iCDLTn values for the 'STOKES' dimension are inconsistent with a
541 * Stokes coordinate definition.
542 *
543 * @see #fromImageHeader(Header)
544 * @see Parameters#fillTableHeader(Header, int, int)
545 *
546 * @since 1.20
547 */
548 @SuppressWarnings({"unchecked", "rawtypes"})
549 public static Map.Entry<Integer, Parameters> fromTableHeader(Header header, int column)
550 throws IndexOutOfBoundsException, FitsException {
551 if (column < 0) {
552 throw new IndexOutOfBoundsException("Invalid Java column index " + column);
553 }
554
555 String dims = header.getStringValue(Standard.TDIMn.n(++column));
556 if (dims == null) {
557 throw new FitsException("Missing TDIM" + column + " in header");
558 }
559
560 StringTokenizer tokens = new StringTokenizer(dims, "(, )");
561 int n = tokens.countTokens();
562
563 for (int i = 1; i <= n; i++) {
564 String d = tokens.nextToken();
565
566 if (Stokes.CTYPE.equalsIgnoreCase(header.getStringValue(WCS.nCTYPn.n(i, column)))) {
567 if (header.getDoubleValue(WCS.nCRPXn.n(i, column), 1.0) != 1.0) {
568 throw new FitsException("Invalid Stokes " + WCS.nCRPXn.n(i, column).key() + " value: "
569 + header.getDoubleValue(WCS.nCRPXn.n(i, column)) + ", expected 1");
570 }
571
572 Parameters p = forCoords(header.getDoubleValue(WCS.nCRVLn.n(i, column), 0.0),
573 header.getDoubleValue(WCS.nCDLTn.n(i, column), 1.0), Integer.parseInt(d));
574
575 return new AbstractMap.SimpleImmutableEntry(n - i, p);
576 }
577 }
578
579 return null;
580 }
581 }