uk.ac.starlink.fits

## Class FitsNdxHandler

- java.lang.Object
- - uk.ac.starlink.fits.FitsNdxHandler

-     public class FitsNdxHandler
      extends java.lang.Object

  Turns URLs which reference FITS files or HDUs into Ndx objects.

  ### FITS file format for NDXs

  When writing an NDX into FITS format, the image array is written as the primary HDU. The headers of this HDU also contain a card with the name "NDX_XML", whose value is a relative URL (of the form '#n', where n is an HDU number) pointing to the HDU in the same FITS file in which XML metadata concerning the NDX's structure can be found. This XML is stored as the sole (character) element of a table extension. Other HDUs may be written if more are needed, for instance the variance and quality arrays. The resulting FITS file is therefore a self-contained copy of the NDX's data (array components) and metadata (XML stored in a table component). Software which is not NDX-aware can see the data just by looking at the primary HDU.

  When reading an NDX from a FITS file, the handler will look for the NDX_XML header; if one is found it will retrieve the metadata from the XML stored in the referenced table extension as described above. If this header is not present, it will make an NDX with no components apart from the image array it is pointed at and any WCS defined by FITS WCS headers in that HDU in the normal way.

  The coordinate system information of an NDX written to a FITS file is currently written to the Image HDU for use by non-NDX-aware software. However, the WCS is read from the XML if present, so in the case of discrepancies between the two the WCS represented in the FITS headers may be out of date.

  ### URL format

  URLs are given in the same format as for the `FitsArrayBuilder` class. If an HDU other than the first one is referenced, that is where the NDX_XML header will be sought.

  This is a singleton class; use `getInstance()` to get an instance.

  Version:
    $Id$
  Author:
    Mark Taylor (Starlink), Norman Gray

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static FitsNdxHandler` | `getInstance()` Returns a FitsNdxHandler.
    `boolean` | `makeBlankNdx(java.net.URL url, Ndx template)`
    `org.w3c.dom.Document` | `makeHdxDocument(java.net.URL url)`
    `javax.xml.transform.Source` | `makeHdxSource(java.net.URL url)`
    `Ndx` | `makeNdx(java.net.URL url, uk.ac.starlink.array.AccessMode mode)`
    `void` | `outputNdx(nom.tam.util.ArrayDataOutput strm, java.net.URL url, Ndx ndx)` Writes an NDX to a given output stream.
    `boolean` | `outputNdx(java.net.URL url, Ndx ndx)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getInstance

          public static FitsNdxHandler getInstance()

      Returns a FitsNdxHandler.
      Returns:
        the sole instance of this class

    - #### makeNdx

          public Ndx makeNdx(java.net.URL url,
                             uk.ac.starlink.array.AccessMode mode)
                      throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### makeBlankNdx

          public boolean makeBlankNdx(java.net.URL url,
                                      Ndx template)
                               throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### outputNdx

          public boolean outputNdx(java.net.URL url,
                                   Ndx ndx)
                            throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### outputNdx

          public void outputNdx(nom.tam.util.ArrayDataOutput strm,
                                java.net.URL url,
                                Ndx ndx)
                         throws java.io.IOException

      Writes an NDX to a given output stream. The stream is not closed following the write.
      Parameters:
        `strm` - the stream to which the NDX should be written
        `url` - the URL represented by the stream; may be `null`
        `ndx` - the ndx to write
      Throws:
        `java.io.IOException`

    - #### makeHdxDocument

          public org.w3c.dom.Document makeHdxDocument(java.net.URL url)
                                               throws HdxException

      Throws:
        `HdxException`

    - #### makeHdxSource

          public javax.xml.transform.Source makeHdxSource(java.net.URL url)
                                                   throws HdxException

      Throws:
        `HdxException`

Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.