1 package nom.tam.fits; 2 3 import java.io.PrintStream; 4 import java.lang.reflect.Array; 5 import java.util.ArrayList; 6 import java.util.Hashtable; 7 import java.util.Set; 8 9 import nom.tam.fits.header.Bitpix; 10 import nom.tam.fits.header.Standard; 11 import nom.tam.util.ArrayDataOutput; 12 import nom.tam.util.ArrayFuncs; 13 import nom.tam.util.FitsOutput; 14 15 /* 16 * #%L 17 * nom.tam FITS library 18 * %% 19 * Copyright (C) 2004 - 2024 nom-tam-fits 20 * %% 21 * This is free and unencumbered software released into the public domain. 22 * 23 * Anyone is free to copy, modify, publish, use, compile, sell, or 24 * distribute this software, either in source code form or as a compiled 25 * binary, for any purpose, commercial or non-commercial, and by any 26 * means. 27 * 28 * In jurisdictions that recognize copyright laws, the author or authors 29 * of this software dedicate any and all copyright interest in the 30 * software to the public domain. We make this dedication for the benefit 31 * of the public at large and to the detriment of our heirs and 32 * successors. We intend this dedication to be an overt act of 33 * relinquishment in perpetuity of all present and future rights to this 34 * software under copyright law. 35 * 36 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 37 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 38 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 39 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 40 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 41 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 42 * OTHER DEALINGS IN THE SOFTWARE. 43 * #L% 44 */ 45 46 import static nom.tam.fits.header.Standard.BITPIX; 47 import static nom.tam.fits.header.Standard.GCOUNT; 48 import static nom.tam.fits.header.Standard.GROUPS; 49 import static nom.tam.fits.header.Standard.NAXIS; 50 import static nom.tam.fits.header.Standard.NAXISn; 51 import static nom.tam.fits.header.Standard.PCOUNT; 52 import static nom.tam.fits.header.Standard.SIMPLE; 53 import static nom.tam.fits.header.Standard.XTENSION; 54 import static nom.tam.fits.header.Standard.XTENSION_IMAGE; 55 56 /** 57 * Random groups header/data unit. Random groups were an early attempt at extending FITS support beyond images, and was 58 * eventually superseded by binary tables, which offer the same functionality and more in a more generic way. The use of 59 * random group HDUs is discouraged, even by the FITS standard. Some old radio data may be packaged in this format. Thus 60 * apart from provided limited support for reading such data, users should not create random groups anew. 61 * {@link BinaryTableHDU} offers a much more flexible and capable way for storing an ensemble of parameters, arrays, and 62 * more. 63 * <p> 64 * Note that the internal storage of random groups is a <code>Object[ngroups][2]</code> array. The first element of each 65 * group (row) is a 1D array of parameter data of a numerical primitive type (e.g. <code>short[]</code>, 66 * <code>double[]</code>). The second element in each group (row) is an image of the same element type as the 67 * parameters. When analyzing group data structure only the first group is examined, but for a valid FITS file all 68 * groups must have the same structure. 69 * <p> 70 * As of version 1.19, we provide support for accessing parameters by names including building up higher-precision 71 * values by combining multiple related parameter conversion recipes through scalings and offsets, as described in the 72 * FITS standard (e.g. combining 3 or 4 related <code>byte</code> parameter values to obtain a full-precision 32-bit 73 * <code>float</code> parameter value when <code>BITPIX</code> is 8). 74 * </p> 75 * 76 * @see BinaryTableHDU 77 */ 78 @SuppressWarnings("deprecation") 79 public class RandomGroupsHDU extends BasicHDU<RandomGroupsData> { 80 81 private Hashtable<String, Parameter> parameters; 82 83 @Override 84 protected final String getCanonicalXtension() { 85 return Standard.XTENSION_IMAGE; 86 } 87 88 /** 89 * @deprecated (<i>for internal use</i>) Will reduce visibility in the future 90 * 91 * @return a random groups data structure from an array of objects representing the data. 92 * 93 * @param o the array of object to create the random groups 94 * 95 * @throws FitsException if the data could not be created. 96 */ 97 @Deprecated 98 public static RandomGroupsData encapsulate(Object o) throws FitsException { 99 if (o instanceof Object[][]) { 100 return new RandomGroupsData((Object[][]) o); 101 } 102 throw new FitsException("Attempt to encapsulate invalid data in Random Group"); 103 } 104 105 static Object[] generateSampleRow(Header h) throws FitsException { 106 107 int ndim = h.getIntValue(NAXIS, 0) - 1; 108 int[] dims = new int[ndim]; 109 110 Class<?> baseClass = Bitpix.fromHeader(h).getNumberType(); 111 112 // Note that we have to invert the order of the axes 113 // for the FITS file to get the order in the array we 114 // are generating. Also recall that NAXIS1=0, so that 115 // we have an 'extra' dimension. 116 117 for (int i = 0; i < ndim; i++) { 118 long cdim = h.getIntValue(NAXISn.n(i + 2), 0); 119 if (cdim < 0) { 120 throw new FitsException("Invalid array dimension:" + cdim); 121 } 122 dims[ndim - i - 1] = (int) cdim; 123 } 124 125 Object[] sample = new Object[2]; 126 sample[0] = ArrayFuncs.newInstance(baseClass, h.getIntValue(PCOUNT)); 127 sample[1] = ArrayFuncs.newInstance(baseClass, dims); 128 129 return sample; 130 } 131 132 /** 133 * Check if this data is compatible with Random Groups structure. Must be an <code>Object[nGroups][2]</code> 134 * structure with both elements of each group having the same base type and the first element being a simple 135 * primitive array. We do not check anything but the first row. 136 * 137 * @deprecated (<i>for internal use</i>) Will reduce visibility in the future 138 * 139 * @param potentialData data to check 140 * 141 * @return is this data compatible with Random Groups structure 142 */ 143 @Deprecated 144 public static boolean isData(Object potentialData) { 145 if (potentialData instanceof Object[][]) { 146 Object[][] o = (Object[][]) potentialData; 147 if (o.length > 0 && o[0].length == 2 && // 148 ArrayFuncs.getBaseClass(o[0][0]) == ArrayFuncs.getBaseClass(o[0][1])) { 149 String cn = o[0][0].getClass().getName(); 150 if (cn.length() == 2 && cn.charAt(1) != 'Z' || cn.charAt(1) != 'C') { 151 return true; 152 } 153 } 154 } 155 return false; 156 } 157 158 /** 159 * @deprecated (<i>for internal use</i>) Will reduce visibility in the future 160 * 161 * @return Is this a random groups header? 162 * 163 * @param hdr The header to be tested. 164 */ 165 @Deprecated 166 public static boolean isHeader(Header hdr) { 167 168 if (hdr.getBooleanValue(SIMPLE)) { 169 return hdr.getBooleanValue(GROUPS); 170 } 171 172 String xtension = hdr.getStringValue(XTENSION); 173 xtension = xtension == null ? "" : xtension.trim(); 174 if (XTENSION_IMAGE.equals(xtension)) { 175 return hdr.getBooleanValue(GROUPS); 176 } 177 178 return false; 179 } 180 181 /** 182 * Prepares a data object into which the actual data can be read from an input subsequently or at a later time. 183 * 184 * @deprecated (<i>for internal use</i>) Will reduce visibility in the future 185 * 186 * @param header The FITS header that describes the data 187 * 188 * @return A data object that support reading content from a stream. 189 * 190 * @throws FitsException if the data could not be prepared to prescriotion. 191 */ 192 @Deprecated 193 public static RandomGroupsData manufactureData(Header header) throws FitsException { 194 195 int gcount = header.getIntValue(GCOUNT, -1); 196 int pcount = header.getIntValue(PCOUNT, -1); 197 198 if (!header.getBooleanValue(GROUPS) || header.getIntValue(NAXISn.n(1), -1) != 0 || gcount < 0 || pcount < 0 199 || header.getIntValue(NAXIS) < 2) { 200 throw new FitsException("Invalid Random Groups Parameters"); 201 } 202 203 return new RandomGroupsData(gcount, generateSampleRow(header)); 204 } 205 206 /** 207 * @deprecated (<i>for internal use</i>) Will reduce visibility in the future 208 * 209 * @return Make a header point to the given object. 210 * 211 * @param d The random groups data the header should describe. 212 * 213 * @throws FitsException if the operation failed 214 */ 215 @Deprecated 216 static Header manufactureHeader(Data d) throws FitsException { 217 218 if (d == null) { 219 throw new FitsException("Attempt to create null Random Groups data"); 220 } 221 Header h = new Header(); 222 d.fillHeader(h); 223 return h; 224 225 } 226 227 /** 228 * Creates a random groups HDU from an <code>Object[nGroups][2]</code> array. Prior to 1.18, we used 229 * {@link Fits#makeHDU(Object)} to create random groups HDUs automatically from matching data. However, FITS 230 * recommends using binary tables instead of random groups in general, and this type of HDU is included in the 231 * standard only to support reading some older radio data. Hence, as of 1.18 {@link Fits#makeHDU(Object)} will never 232 * return random groups HDUs any longer, and will instead create binary (or ASCII) table HDUs instead. If the need 233 * arises to create new random group HDUs programatically, beyond reading of older files, then this method can take 234 * its place. 235 * 236 * @param data The random groups table. The second dimension must be 2. The first element in each group 237 * (row) must be a 1D numerical primitive array, while the second element may be a 238 * multi-dimensional image of the same element type. All rows must consists of arrays of 239 * the same primitive numerical types and sized, e.g. 240 * <code>{ float[5], float[7][2] }</code> or <code>{ short[3], short[2][2][4] }</code>. 241 * 242 * @return a new random groups HDU, which encapsulated the supploed data table. 243 * 244 * @throws FitsException if the seconds dimension of the array is not 2. 245 * 246 * @see Fits#makeHDU(Object) 247 * 248 * @since 1.18 249 */ 250 public static RandomGroupsHDU createFrom(Object[][] data) throws FitsException { 251 if (!isData(data)) { 252 throw new FitsException("Type or layout of data is not random groups compatible."); 253 } 254 RandomGroupsData d = encapsulate(data); 255 return new RandomGroupsHDU(manufactureHeader(d), d); 256 } 257 258 private void parseParameters(Header header) { 259 // Parse the parameter descriptions from the header 260 int nparms = header.getIntValue(Standard.PCOUNT); 261 262 parameters = new Hashtable<>(); 263 264 for (int i = 1; i <= nparms; i++) { 265 String name = header.getStringValue(Standard.PTYPEn.n(i)); 266 if (name == null) { 267 continue; 268 } 269 270 Parameter p = parameters.get(name); 271 if (p == null) { 272 p = new Parameter(); 273 parameters.put(name, p); 274 } 275 276 p.components.add(new ParameterConversion(header, i)); 277 } 278 } 279 280 /** 281 * Create an HDU from the given header and data. 282 * 283 * @deprecated (<i>for internal use</i>) Its visibility should be reduced to package level in the future. 284 * 285 * @param header header to use 286 * @param data data to use 287 */ 288 public RandomGroupsHDU(Header header, RandomGroupsData data) { 289 super(header, data); 290 291 if (header == null) { 292 return; 293 } 294 295 parseParameters(header); 296 } 297 298 @Override 299 public void info(PrintStream stream) { 300 301 stream.println("Random Groups HDU"); 302 if (myHeader != null) { 303 stream.println(" HeaderInformation:"); 304 stream.println(" Ngroups:" + myHeader.getIntValue(GCOUNT)); 305 stream.println(" Npar: " + myHeader.getIntValue(PCOUNT)); 306 stream.println(" BITPIX: " + myHeader.getIntValue(BITPIX)); 307 stream.println(" NAXIS: " + myHeader.getIntValue(NAXIS)); 308 for (int i = 0; i < myHeader.getIntValue(NAXIS); i++) { 309 stream.println(" NAXIS" + (i + 1) + "= " + myHeader.getIntValue(NAXISn.n(i + 1))); 310 } 311 } else { 312 stream.println(" No Header Information"); 313 } 314 315 Object[][] data = null; 316 if (myData != null) { 317 try { 318 data = myData.getData(); 319 } catch (FitsException e) { 320 // nothing to do... 321 } 322 } 323 324 if (data == null || data.length < 1 || data[0].length != 2) { 325 stream.println(" Invalid/unreadable data"); 326 } else { 327 stream.println(" Number of groups:" + data.length); 328 stream.println(" Parameters: " + ArrayFuncs.arrayDescription(data[0][0])); 329 stream.println(" Data:" + ArrayFuncs.arrayDescription(data[0][1])); 330 } 331 } 332 333 /** 334 * Returns the number of parameter bytes (per data group) accompanying each data object in the group. 335 */ 336 @Override 337 public int getParameterCount() { 338 return super.getParameterCount(); 339 } 340 341 /** 342 * Returns the number of data objects (of identical shape and size) that are group together in this HDUs data 343 * segment. 344 */ 345 @Override 346 public int getGroupCount() { 347 return super.getGroupCount(); 348 } 349 350 /** 351 * Check that this HDU has a valid header. 352 * 353 * @return <CODE>true</CODE> if this HDU has a valid header. 354 */ 355 public boolean isHeader() { 356 return isHeader(myHeader); 357 } 358 359 /** 360 * Returns the name of the physical unit in which image data are represented. 361 * 362 * @return the standard name of the physical unit in which the image is expressed, e.g. <code>"Jy beam^{-1}"</code>. 363 */ 364 @Override 365 public String getBUnit() { 366 return super.getBUnit(); 367 } 368 369 /** 370 * Returns the integer value that signifies blank (missing or <code>null</code>) data in an integer image. 371 * 372 * @return the integer value used for identifying blank / missing data in integer images. 373 * 374 * @throws FitsException if the header does not specify a blanking value or if it is not appropriate for the type of 375 * imge (that is not an integer type image) 376 */ 377 @Override 378 public long getBlankValue() throws FitsException { 379 if (getBitpix().getHeaderValue() < 0) { 380 throw new FitsException("No integer blanking value in floating-point images."); 381 } 382 return super.getBlankValue(); 383 } 384 385 /** 386 * Returns the floating-point increment between adjacent integer values in the image. Strictly speaking, only 387 * integer-type images should define a quantization scaling, but there is no harm in having this value in 388 * floating-point images also -- which may be interpreted as a hint for quantization, perhaps. 389 * 390 * @return the floating-point quantum that corresponds to the increment of 1 in the integer data representation. 391 * 392 * @see #getBZero() 393 */ 394 @Override 395 public double getBScale() { 396 return super.getBScale(); 397 } 398 399 /** 400 * Returns the floating-point value that corresponds to an 0 integer value in the image. Strictly speaking, only 401 * integer-type images should define a quantization scaling, but there is no harm in having this value in 402 * floating-point images also -- which may be interpreted as a hint for quantization, perhaps. 403 * 404 * @return the floating point value that correspond to the integer 0 in the image data. 405 * 406 * @see #getBScale() 407 */ 408 @Override 409 public double getBZero() { 410 return super.getBZero(); 411 } 412 413 @Override 414 public void write(ArrayDataOutput stream) throws FitsException { 415 if (stream instanceof FitsOutput) { 416 if (!((FitsOutput) stream).isAtStart()) { 417 throw new FitsException("Random groups are only permitted in the primary HDU"); 418 } 419 } 420 super.write(stream); 421 } 422 423 /** 424 * Returns a list of parameter names bundled along the images in each group, as extracted from the PTYPE_n_ header 425 * entries. 426 * 427 * @return A set containing the parameter names contained in this HDU 428 * 429 * @see #getParameter(String, int) 430 * 431 * @since 1.19 432 */ 433 public Set<String> getParameterNames() { 434 return parameters.keySet(); 435 } 436 437 /** 438 * Returns the value for a given group parameter. 439 * 440 * @param name the parameter name 441 * @param group the zero-based group index 442 * 443 * @return the stored parameter value in the specified group, or {@link Double#NaN} 444 * if the there is no such group. 445 * 446 * @throws ArrayIndexOutOfBoundsException if the group index is out of bounds. 447 * @throws FitsException if the deferred parameter data cannot be accessed 448 * 449 * @see #getParameterNames() 450 * @see RandomGroupsData#getImage(int) 451 * 452 * @since 1.19 453 */ 454 public double getParameter(String name, int group) throws ArrayIndexOutOfBoundsException, FitsException { 455 Parameter p = parameters.get(name); 456 if (p == null) { 457 return Double.NaN; 458 } 459 460 return p.getValue(getData().getParameterArray(group)); 461 } 462 463 /** 464 * A conversion recipe from the native BITPIX type to a floating-point value. Each parameter may have multiple such 465 * recipes, the sum of which can provide the required precision for the parameter regardless the BITPIX storage 466 * type. 467 * 468 * @author Attila Kovacs 469 * 470 * @since 1.19 471 */ 472 private static final class ParameterConversion { 473 private int index; 474 private double scaling; 475 private double offset; 476 477 private ParameterConversion(Header h, int n) { 478 index = n - 1; 479 scaling = h.getDoubleValue(Standard.PSCALn.n(n), 1.0); 480 offset = h.getDoubleValue(Standard.PZEROn.n(n), 0.0); 481 } 482 } 483 484 /** 485 * Represents a single parameter in the random groups data. 486 * 487 * @author Attila Kovacs 488 * 489 * @since 1.19 490 */ 491 private static final class Parameter { 492 private ArrayList<ParameterConversion> components = new ArrayList<>(); 493 494 private double getValue(Object array) { 495 double value = 0.0; 496 for (ParameterConversion c : components) { 497 double x = Array.getDouble(array, c.index); 498 value += c.scaling * x + c.offset; 499 } 500 return value; 501 } 502 } 503 504 }