Package nom.tam.fits

Class FitsFactory

java.lang.Object
nom.tam.fits.FitsFactory
public final class FitsFactory extends Object
Controls the creation of HDUs to encapsulate a variery of data, based on a few configuration switches. The switches allow for toggling support for different conventions to set the desired compatibility level. The default settings produce FITS that are compatibel with version 4.0 of the standard (the latest at the time of writing this). The switches may also be used to make this library more backward compatible with its previous version also.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    FITS_BLOCK_SIZE
    the size of a FITS block in bytes.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Data
    dataFactory(Header hdr)
    Deprecated.
    (for internal use) Will reduce visibility in the future
    static boolean
    getAllowTerminalJunk()
    Whether extra bytes are tolerated after the end of an HDU.
    static boolean
    getCheckAsciiStrings()
    Checks whether we should check and validated ASCII strings that goe into FITS.
    static IHierarchKeyFormatter
    getHierarchFormater()
    Returns the formatter instance for HIERARCH style keywords.
    static boolean
    getUseAsciiTables()
    whether ASCII tables should be used where feasible.
    static boolean
    getUseHierarch()
    Whether we can use HIERARCH style keywords.
    static BasicHDU<?>
    hduFactory(Object o)
    Deprecated.
    Use Fits.makeHDU(Object) instead (this method may either be migrated to Fits entirely or else have visibility reduced to the package level).
    static <DataClass extends Data>
    BasicHDU<DataClass>
    hduFactory(Header hdr, DataClass d)
    Deprecated.
    (for internal use)/ Will reduce visibility in the future
    static BasicHDU<?>
    HDUFactory(Object o)
    Deprecated.
    Use Fits.makeHDU(Object) instead (will removed in the future.
    static <DataClass extends Data>
    BasicHDU<DataClass>
    HDUFactory(Header hdr, DataClass d)
    Deprecated.
    (duplicate method for internal use) Same as hduFactory(Header, Data), and will be removed in the future.
    static boolean
    isAllowHeaderRepairs()
    Whether we allow 3rd party FITS headers to be in violation of the standard, attempting to make sense of corrupted header data as much as possible.
    static boolean
    isLongStringsEnabled()
    Whether we allow storing long string in the header, which do not fit into a single 80-byte header record.
    static boolean
    isSkipBlankAfterAssign()
    Deprecated.
    The FITS standard is very explicit that assignment must be "= " (equals followed by a blank space).
    static boolean
    isUseExponentD()
    Whether the letter 'D' may replace 'E' in the exponential notation of doubl-precision values.
    static boolean
    isUseUnicodeChars()
    Whether char[] arrays are written as 16-bit integers (short[]) int binary tables as opposed as FITS character arrays (byte[] with column type 'A').
    static void
    setAllowHeaderRepairs(boolean allowHeaderRepairs)
    Do we allow automatic header repairs, like missing end quotes?
    static void
    setAllowTerminalJunk(boolean allowTerminalJunk)
    Do we allow junk after a valid FITS file?
    static void
    setCheckAsciiStrings(boolean checkAsciiStrings)
    Enable/Disable checking of strings values used in tables to ensure that they are within the range specified by the FITS standard.
    static void
    setDefaults()
    Restores all settings to their default values.
    static void
    setHierarchFormater(IHierarchKeyFormatter formatter)
    There is not a real standard how to write hierarch keys, default we use the one where every key is separated by a blank.
    static void
    setLongStringsEnabled(boolean longStringsEnabled)
    Enable/Disable longstring support.
    static void
    setSkipBlankAfterAssign(boolean skipBlankAfterAssign)
    Deprecated.
    The FITS standard is very explicit that assignment must be "= " (equals followed by a blank space).
    static void
    setUseAsciiTables(boolean useAsciiTables)
    Indicate whether ASCII tables should be used where feasible.
    static void
    setUseExponentD(boolean allowExponentD)
    Sets whether 'D' may be used instead of 'E' to mark the exponent for a floating point value with precision beyond that of a 32-bit float.
    static void
    setUseHierarch(boolean useHierarch)
    Enable/Disable hierarchical keyword processing.
    static void
    setUseUnicodeChars(boolean value)
    Enable/Disable writing char[] arrays as short[] in FITS binary tables (with column type 'I'), instead of as standard FITS 1-byte ASCII characters (with column type 'A').
    static ExecutorService
    threadPool()
    Returns the common thread pool that we use for processing FITS files.
    static void
    useThreadLocalSettings(boolean useThreadSettings)
    Use thread local settings for the current thread instead of the global ones if the parameter is set to true, else use the shared global settings.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • FITS_BLOCK_SIZE

      public static final int FITS_BLOCK_SIZE
      the size of a FITS block in bytes.
      See Also:

  • Method Details

    • dataFactory

      @Deprecated public static Data dataFactory(Header hdr) throws FitsException
      Deprecated.
      (for internal use) Will reduce visibility in the future
      Parameters:
      hdr - header to create the data from
      Returns:
      Given a Header construct an appropriate data.
      Throws:
      FitsException - if the header did not contain enough information to detect the type of the data

    • isUseExponentD

      public static boolean isUseExponentD()
      Whether the letter 'D' may replace 'E' in the exponential notation of doubl-precision values. FITS allows (even encourages) the use of 'D' to indicate double-recision values. For example to disambiguate between 1.37E-3 (single-precision) and 1.37D-3 (double-precision), which are not exatly the same value in binary representation.
      Returns:
      Do we allow automatic header repairs, like missing end quotes?
      Since:
      1.16
      See Also:

    • isUseUnicodeChars

      public static boolean isUseUnicodeChars()
      Whether char[] arrays are written as 16-bit integers (short[]) int binary tables as opposed as FITS character arrays (byte[] with column type 'A'). See more explanation in setUseUnicodeChars(boolean).
      Returns:
      true if char[] get written as 16-bit integers in binary table columns (column type 'I'), or as FITS 1-byte ASCII character arrays (as is always the case for String) with column type 'A'.
      Since:
      1.16
      See Also:

    • getAllowTerminalJunk

      public static boolean getAllowTerminalJunk()
      Whether extra bytes are tolerated after the end of an HDU. Normally if there is additional bytes present after an HDU, it would be the beginning of another HDU -- which must start with a very specific sequence of bytes. So, when there is data beyond the end of an HDU that does not appear to be another HDU, it's junk. We can either ignore it, or throw an exception.
      Returns:
      Is terminal junk (i.e., non-FITS data following a valid HDU) allowed.
      See Also:

    • isAllowHeaderRepairs

      public static boolean isAllowHeaderRepairs()
      Whether we allow 3rd party FITS headers to be in violation of the standard, attempting to make sense of corrupted header data as much as possible.
      Returns:
      Do we allow automatic header repairs, like missing end quotes?
      See Also:

    • getHierarchFormater

      public static IHierarchKeyFormatter getHierarchFormater()
      Returns the formatter instance for HIERARCH style keywords. Our own standard is to define such keywords internally as starting with the string HIERARCH. followed by a dot-separated hierarchy, or just an unusually long FITS keywords that cannot be represented by a standard 8-byte keyword. The HIERARCH formatted will take such string keywords and will format them according to its rules when writing them to FITS headers.
      Returns:
      the formatter to use for hierarch keys.
      See Also:

    • getUseHierarch

      public static boolean getUseHierarch()
      Whether we can use HIERARCH style keywords. Such keywords are not part of the current FITS standard, although they constitute a recognised convention. Even if other programs may not process HIRARCH keywords themselves, there is generally no harm to putting them into FITS headers, since the convention is such that these keywords will be simply treated as comments by programs that do not recognise them.
      Returns:
      true if we are processing HIERARCH style keywords
      See Also:

    • getUseAsciiTables

      public static boolean getUseAsciiTables()
      whether ASCII tables should be used where feasible.
      Returns:
      true if we ASCII tables are allowed.
      See Also:

    • getCheckAsciiStrings

      public static boolean getCheckAsciiStrings()
      Checks whether we should check and validated ASCII strings that goe into FITS. FITS only allows ASCII characters between 0x20 and 0x7E in ASCII tables.
      Returns:
      Get the current status for string checking.
      See Also:

    • isLongStringsEnabled

      public static boolean isLongStringsEnabled()
      Whether we allow storing long string in the header, which do not fit into a single 80-byte header record. Such strings are then wrapped into multiple consecutive header records, OGIP 1.0 standard -- which is nart of FITS 4.0, and was a recognised convention before.
      Returns:
      true If long string support is enabled.
      See Also:

    • isSkipBlankAfterAssign

      @Deprecated public static boolean isSkipBlankAfterAssign()
      Deprecated.
      The FITS standard is very explicit that assignment must be "= " (equals followed by a blank space). If we allow skipping the space, it will result in a non-standard FITS, that is likely to break compatibility with other tools.
      Returns:
      whether to use only "=", instead of the standard "= " between the keyword and the value.
      See Also:

    • hduFactory

      @Deprecated public static <DataClass extends Data> BasicHDU<DataClass> hduFactory(Header hdr, DataClass d) throws FitsException
      Deprecated.
      (for internal use)/ Will reduce visibility in the future
      .
      Type Parameters:
      DataClass - the class of the data
      Parameters:
      hdr - the header, including a description of the data layout.
      d - the type of data object
      Returns:
      Given Header and data objects return the appropriate type of HDU.
      Throws:
      FitsException - if the operation failed

    • hduFactory

      public static BasicHDU<?> hduFactory(Object o) throws FitsException
      Deprecated.
      Use Fits.makeHDU(Object) instead (this method may either be migrated to Fits entirely or else have visibility reduced to the package level).
      Creates an HDU that wraps around the specified data object. The HDUs header will be created and populated with the essential description of the data. The following HDU types may be returned depending on the nature of the argument:
      • NullDataHDU -- if the argument is null
      • ImageHDU -- if the argument is a regular numerical array, such as a double[], float[][], or short[][][]
      • BinaryTableHDU -- the the argument is an Object[rows][cols] type array with a regular structure and supported column data types, provided that it cannot be represented by an ASCII table OR if getUseAsciiTables() is false
      • AsciiTableHDU -- Like above, but only when the data can be represented by an ASCII table AND getUseAsciiTables() is true
      Parameters:
      o - The object to be described.
      Returns:
      An appropriate HDU to encapsulate the given Java data object
      Throws:
      FitsException - if the parameter could not be converted to a HDU because the binary representation of the object is not known..

    • HDUFactory

      @Deprecated public static <DataClass extends Data> BasicHDU<DataClass> HDUFactory(Header hdr, DataClass d) throws FitsException
      Deprecated.
      (duplicate method for internal use) Same as hduFactory(Header, Data), and will be removed in the future.
      Type Parameters:
      DataClass - the class of the data
      Parameters:
      hdr - the header of the date
      d - the data
      Returns:
      Given Header and data objects return the appropriate type of HDU.
      Throws:
      FitsException - if the operation failed

    • HDUFactory

      @Deprecated public static BasicHDU<?> HDUFactory(Object o) throws FitsException
      Deprecated.
      Use Fits.makeHDU(Object) instead (will removed in the future. Duplicate of hduFactory(Object)
      Parameters:
      o - The object to be described.
      Returns:
      Given an object, create the appropriate FITS header to describe it.
      Throws:
      FitsException - if the parameter could not be converted to a hdu.

    • setDefaults

      public static void setDefaults()
      Restores all settings to their default values.
      Since:
      1.16

    • setUseExponentD

      public static void setUseExponentD(boolean allowExponentD)
      Sets whether 'D' may be used instead of 'E' to mark the exponent for a floating point value with precision beyond that of a 32-bit float.
      Parameters:
      allowExponentD - if true D will be used instead of E to indicate the exponent of a decimal with more precision than a 32-bit float.
      Since:
      1.16
      See Also:

    • setAllowTerminalJunk

      public static void setAllowTerminalJunk(boolean allowTerminalJunk)
      Do we allow junk after a valid FITS file?
      Parameters:
      allowTerminalJunk - value to set
      See Also:

    • setAllowHeaderRepairs

      public static void setAllowHeaderRepairs(boolean allowHeaderRepairs)
      Do we allow automatic header repairs, like missing end quotes?
      Parameters:
      allowHeaderRepairs - value to set
      See Also:

    • setCheckAsciiStrings

      public static void setCheckAsciiStrings(boolean checkAsciiStrings)
      Enable/Disable checking of strings values used in tables to ensure that they are within the range specified by the FITS standard. The standard only allows the values 0x20 - 0x7E with null bytes allowed in one limited context. Disabled by default.
      Parameters:
      checkAsciiStrings - value to set
      See Also:

    • setHierarchFormater

      public static void setHierarchFormater(IHierarchKeyFormatter formatter)
      There is not a real standard how to write hierarch keys, default we use the one where every key is separated by a blank. If you want or need another format assing the formater here.
      Parameters:
      formatter - the hierarch key formatter.

    • setLongStringsEnabled

      public static void setLongStringsEnabled(boolean longStringsEnabled)
      Enable/Disable longstring support.
      Parameters:
      longStringsEnabled - value to set
      See Also:

    • setSkipBlankAfterAssign

      @Deprecated public static void setSkipBlankAfterAssign(boolean skipBlankAfterAssign)
      Deprecated.
      The FITS standard is very explicit that assignment must be "= " (equals followed by a blank space). It is also very specific that string values must have their opening quote in byte 11 (counted from 1). If we allow skipping the space, we will violate both standards in a way that is likely to break compatibility with other tools.
      If set to true the blank after the assign in the header cards in not written. The blank is stronly recommendet but in some cases it is important that it can be ommitted.
      Parameters:
      skipBlankAfterAssign - value to set
      See Also:

    • setUseAsciiTables

      public static void setUseAsciiTables(boolean useAsciiTables)
      Indicate whether ASCII tables should be used where feasible.
      Parameters:
      useAsciiTables - value to set

    • setUseHierarch

      public static void setUseHierarch(boolean useHierarch)
      Enable/Disable hierarchical keyword processing.
      Parameters:
      useHierarch - value to set

    • setUseUnicodeChars

      public static void setUseUnicodeChars(boolean value)

      Enable/Disable writing char[] arrays as short[] in FITS binary tables (with column type 'I'), instead of as standard FITS 1-byte ASCII characters (with column type 'A'). The old default of this library has been to use unicode, and that behavior remains the default — the same as setting the argument to true. On the flipside, setting it to false provides more convergence between the handling of char[] columns and the nearly identical String columns, which have already been restricted to ASCII before.

      Parameters:
      value - true to write char[] arrays as if short[] with column type 'I' to binary tables (old behaviour, and hence default), or else false to write them as byte[] with column type 'A', the same as for String (preferred behaviour)
      Since:
      1.16
      See Also:

    • threadPool

      public static ExecutorService threadPool()
      Returns the common thread pool that we use for processing FITS files.
      Returns:
      the thread pool for processing FITS files.

    • useThreadLocalSettings

      public static void useThreadLocalSettings(boolean useThreadSettings)
      Use thread local settings for the current thread instead of the global ones if the parameter is set to true, else use the shared global settings.
      Parameters:
      useThreadSettings - true if the thread should not share the global settings.