Package nom.tam.fits

Class ImageData

java.lang.Object
nom.tam.fits.Data
nom.tam.fits.ImageData
All Implemented Interfaces:
FitsElement
Direct Known Subclasses:
NullData, StreamingTileImageData
public class ImageData extends Data

Image data. Essentially these data are a primitive multi-dimensional array, such as a double[], float[][], or short[][][]. Or, as of version 1.20, they may also be ComplexValue types also.

Starting in version 0.9 of the FITS library, this class allows users to defer the reading of images if the FITS data is being read from a file. An ImageTiler object is supplied which can return an arbitrary subset of the image as a one dimensional array -- suitable for manipulation by standard Java libraries. The image data may not be read from the input until the user calls a method that requires the actual data (e.g. the Data.getData() / Data.getKernel(), convertTo(Class) or write(ArrayDataOutput) methods).

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    ImageData()
    Create the equivalent of a null data element.
    ImageData(Object x)
    Create an ImageData object using the specified object to initialize the data array.
    ImageData(Header h)
    (for internal use) Create an array from a header description.

  • Method Summary

    Modifier and Type
    Method
    Description
    ImageData
    convertTo(Class<?> type)
    Converts this image HDU to another image HDU of a different type, possibly using a qunatizer for the integer-decimal conversion of the data elements.
    static ImageData
    from(Object data)
    Creates a new FITS image using the specified primitive numerical Java array containing data.
    final int[]
    getDimensions()
    Returns the dimensions of this image.
    final Quantizer
    getQuantizer()
    Returns the conversion between decimal and integer data representations.
    StandardImageTiler
    getTiler()
    Returns the class that can be used to divide this image into tiles that may be processed separately (and in parallel).
    final Class<?>
    getType()
    Returns the element type of this image in its current representation.
    final boolean
    isComplexValued()
    Checks if the image data is explicitly designated as a complex-valued image.
    static void
    overrideHeaderAxes(Header header, int... sizes)
    (for expert users) Overrides the image size description in the header to the specified Java array dimensions.
    void
    read(ArrayDataInput in)
    Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.
    void
    setBuffer(Buffer data)
    Sets the buffer that may hold a serialized version of the data for this image.
    void
    setQuantizer(Quantizer quant)
    Sets the conversion between decimal and integer data representations.
    ImageHDU
    toHDU()
    Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
    void
    write(ArrayDataOutput o)
    Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.

    Methods inherited from class nom.tam.fits.Data

    calcChecksum, detach, getData, getFileOffset, getKernel, getSize, isDeferred, isEmpty, reset, rewrite, rewriteable

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ImageData

      public ImageData()
      Create the equivalent of a null data element.

    • ImageData

      public ImageData(Header h) throws FitsException
      (for internal use) Create an array from a header description. This is typically how data will be created when reading FITS data from a file where the header is read first. This creates an empty array.
      Parameters:
      h - header to be used as a template.
      Throws:
      FitsException - if there was a problem with the header description.

    • ImageData

      public ImageData(Object x) throws IllegalArgumentException
      Create an ImageData object using the specified object to initialize the data array.
      Parameters:
      x - The initial data array. This should be a primitive array but this is not checked currently.
      Throws:
      IllegalArgumentException - if x is not a suitable primitive array

  • Method Details

    • read

      public void read(ArrayDataInput in) throws FitsException
      Description copied from class: Data

      Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.

      In case the argument is a an instance of RandomAccess input (such as a FitsFile, the call will simply note where in the file the data segment can be found for reading at a later point, only when the data content is accessed. This 'deferred' reading behavior make it possible to process large HDUs even with small amount of RAM, and can result in a significant performance boost when inspectring large FITS files, or using only select content from large FITS files.

      Specified by:
      read in interface FitsElement
      Overrides:
      read in class Data
      Parameters:
      in - The input data stream
      Throws:
      PaddingException - if there is missing padding between the end of the data segment and the enf-of-file.
      FitsException - if the data appears to be corrupted.
      See Also:

    • getTiler

      public StandardImageTiler getTiler()
      Returns the class that can be used to divide this image into tiles that may be processed separately (and in parallel).
      Returns:
      image tiler for this image instance.

    • setBuffer

      public void setBuffer(Buffer data)
      Sets the buffer that may hold a serialized version of the data for this image.
      Parameters:
      data - the buffer that may hold this image's data in serialized form.

    • write

      public void write(ArrayDataOutput o) throws FitsException
      Description copied from interface: FitsElement
      Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.
      Specified by:
      write in interface FitsElement
      Specified by:
      write in class Data
      Parameters:
      o - The data sink.
      Throws:
      FitsException - if the write was unsuccessful.

    • overrideHeaderAxes

      public static void overrideHeaderAxes(Header header, int... sizes) throws FitsException, IllegalArgumentException
      (for expert users) Overrides the image size description in the header to the specified Java array dimensions. Typically users should not call this method, unless they want to define the image dimensions in the absence of the actual complete image data. For example, to describe the dimensions when using low-level writes of an image row-by-row, without ever storing the entire image in memory.
      Parameters:
      header - A FITS image header
      sizes - The array dimensions in Java order (fastest varying index last)
      Throws:
      FitsException - if the size has negative values, or the header is not that for an image
      IllegalArgumentException - should not actually happen
      Since:
      1.18
      See Also:
      • fillHeader(Header)

    • from

      public static ImageData from(Object data) throws IllegalArgumentException
      Creates a new FITS image using the specified primitive numerical Java array containing data.
      Parameters:
      data - A regulatly shaped primitive numerical Java array, which can be multi-dimensional.
      Returns:
      A new FITS image that encapsulates the specified array data.
      Throws:
      IllegalArgumentException - if the argument is not a primitive numerical Java array.
      Since:
      1.19

    • toHDU

      public ImageHDU toHDU() throws FitsException
      Description copied from class: Data
      Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
      Specified by:
      toHDU in class Data
      Returns:
      a HDU object ocntaining the data and its minimal required header description
      Throws:
      FitsException - If the data cannot be converted to an HDU for some reason.

    • setQuantizer

      public void setQuantizer(Quantizer quant)
      Sets the conversion between decimal and integer data representations. The quantizer for the image is set automatically if the image was read from a FITS input, and if any of the associated BSCALE, BZERO, or BLANK keywords were defined in the HDU's header. User may use this methods to set a different quantization or to use no quantization at all when converting between floating-point and integer representations.
      Parameters:
      quant - the quantizer that converts between floating-point and integer data representations, or null to not use quantization and instead rely on simple rounding for decimal-ineger conversions..
      Since:
      1.20
      See Also:

    • getQuantizer

      public final Quantizer getQuantizer()
      Returns the conversion between decimal and integer data representations.
      Returns:
      the quantizer that converts between floating-point and integer data representations, which may be null
      Since:
      1.20
      See Also:

    • getType

      public final Class<?> getType()
      Returns the element type of this image in its current representation.
      Returns:
      The element type of this image, such as int.class, double.class or ComplexValue.class.
      Since:
      1.20
      See Also:

    • getDimensions

      public final int[] getDimensions()
      Returns the dimensions of this image.
      Returns:
      An array containing the sizes along each data dimension, in Java indexing order. The returned array is not used internally, and therefore modifying it will not damage the integrity of the image data.
      Since:
      1.20
      See Also:

    • isComplexValued

      public final boolean isComplexValued()
      Checks if the image data is explicitly designated as a complex-valued image. An image may be designated as complex-valued either because it was created with ComplexValue type data, or because it was read from a FITS file in which one image axis of dimension 2 was designated as an axis containing complex-valued components with the corresponding CTYPEn header keyword set to 'COMPLEX'. The complex-valued deignation checked by this method is not the same as getType(), as it does not necesarily mean that the data itself is currently in ComplexValue type representation. Rather it simply means that this data can be represented as ComplexValue type, possibly after an appropriate conversion to a ComplexValue type.
      Returns:
      true if the data is complex valued or has been explicitly designated as complex valued. Otherwise false.
      Since:
      1.20
      See Also:

    • convertTo

      public ImageData convertTo(Class<?> type) throws FitsException
      Converts this image HDU to another image HDU of a different type, possibly using a qunatizer for the integer-decimal conversion of the data elements. In all other respects, the returned image is identical to the the original. If th conversion is th indetity, it will return itself and the data may remain in deferred mode.
      Parameters:
      type - The primitive numerical type (e.g. int.class or double.class), or else a ComplexValue type in which data should be represented. Complex representations are normally available for data whose first or last CTYPEn axis was described as 'COMPLEX' by the FITS header with a dimensionality is 2 corresponfing to a pair of real and imaginary data elements. Even without the CTYPEn designation, it is always possible to convert to complex all arrays that have a trailing Java dimension (NAXIS1 in FITS) equal to 2.
      Returns:
      An image HDU containing the same data in the chosen representation by another type. (It may be the same as this HDU if the type is unchanged from the original).
      Throws:
      FitsException - if the data cannot be read from the input.
      Since:
      1.20
      See Also: