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:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static class 
    This class describes an array
    protected class 
    This inner class allows the ImageTiler to see if the user has read in the data.
  • Field Summary

    Fields inherited from class nom.tam.fits.Data

    dataSize, fileOffset, input
  • Constructor Summary

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

    Modifier and Type
    Method
    Description
    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.
    protected void
    Describe the structure of this data object in the supplied header.
    static ImageData
    from(Object data)
    Creates a new FITS image using the specified primitive numerical Java array containing data.
    protected Object
    Returns the data content that is currently in memory.
    final int[]
    Returns the dimensions of this image.
    final Quantizer
    Returns the conversion between decimal and integer data representations.
    Returns the class that can be used to divide this image into tiles that may be processed separately (and in parallel).
    protected long
    Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.
    final Class<?>
    Returns the element type of this image in its current representation.
    final boolean
    Checks if the image data is explicitly designated as a complex-valued image.
    protected void
    Load data from the current position of the input into memory.
    static void
    overrideHeaderAxes(Header header, int... sizes)
    (for expert users) Overrides the image size description in the header to the specified Java array dimensions.
    Returns the image specification based on its description in a FITS header.
    void
    Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.
    void
    Sets the buffer that may hold a serialized version of the data for this image.
    void
    Sets the conversion between decimal and integer data representations.
    Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
    void
    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 java.lang.Object

    clone, equals, finalize, 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

    • loadData

      protected void loadData(ArrayDataInput in) throws IOException, FitsException
      Description copied from class: Data

      Load data from the current position of the input into memory. This may be triggered immediately when calling Data.read(ArrayDataInput) if called on a non random accessible input, or else later when data is accessed via Data.ensureData(), for example as a result of a Data.getData() call. This method will not be called unless there is actual data of non-zero size to be read.

      Implementations should create appropriate data structures and populate them from the specified input.

      Specified by:
      loadData in class Data
      Parameters:
      in - The input from which to load data
      Throws:
      IOException - if the data could not be loaded from the input.
      FitsException - if the data is garbled.
      See Also:
    • 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:
      FitsException - if the data appears to be corrupted.
      See Also:
    • getCurrentData

      protected Object getCurrentData()
      Description copied from class: Data
      Returns the data content that is currently in memory. In case of a data object in deferred read state (that is its prescription has been parsed from the header, but no data content was loaded yet from a random accessible input), this call may return null or an object representing empty data.
      Specified by:
      getCurrentData in class Data
      Returns:
      The current data content in memory.
      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.
    • fillHeader

      protected void fillHeader(Header head) throws FitsException
      Description copied from class: Data
      Describe the structure of this data object in the supplied header.
      Specified by:
      fillHeader in class Data
      Parameters:
      head - header to fill with the data from the current data object
      Throws:
      FitsException - if the operation fails
    • getTrueSize

      protected long getTrueSize()
      Description copied from class: Data
      Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.
      Specified by:
      getTrueSize in class Data
      Returns:
      the calculated byte size for the data.
    • parseHeader

      protected ImageData.ArrayDesc parseHeader(Header h) throws FitsException
      Returns the image specification based on its description in a FITS header.
      Parameters:
      h - the FITS header that describes this image with the standard keywords for an image HDU.
      Returns:
      an object that captures the description contained in the header for internal use.
      Throws:
      FitsException - If there was a problem accessing or interpreting the required header values.
    • 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:
    • 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: