Package nom.tam.util

Class Quantizer

java.lang.Object
nom.tam.util.Quantizer
public class Quantizer extends Object

Quantizes floating point values as integers. FITS allows representing floating-point values as integers, e.g. to allow more compact storage at some tolerable level of precision loss. For example, you may store floating-point values (4 bytes) discretized into 64k levels as 16-bit integers. The conversion involves a linear transformation: 

   {float-value}= {scaling} * {int-value} + {offset}

and the inverse transformation: 

   {int-value} = round(({float-value} - {offset}) / {scaling})

The latter floating-point to integer conversion naturally results in some loss of precision, comparable to the level of the scaling factor, i.e. the peration of discrete levels at which information is preserved.

In addition to the scaling conversion, FITS also allows designating an integer blanking value to indicate missing or invalid data, which is mapped to NaN in the floating point representation.

Fits allows for quantized representations of floating-point data both in image HDUs and for columns in binary table HDUs. The quantization parameters are stored differently for the two types of HDUs, using the BSCALE, BZERO, and BLANK keywords for images, and the TSCALn, TZEROn, and TNULLn keywords for individual columns in a table.

Since:
1.20
Author:
Attila Kovacs

  • Constructor Summary

    Constructors
    Constructor
    Description
    Quantizer(double scale, double offset, int blankingValue)
    Constructs a new decimal/integer conversion rule.
    Quantizer(double scale, double offset, Long blankingValue)
    Constructs a new decimal/integer conversion rule.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    editImageHeader(Header h)
    Adds the quantization parameters to an image header,
    void
    editTableHeader(Header h, int col)
    Adds the quantization parameters to a binaty table header,
    static Quantizer
    fromImageHeader(Header h)
    Returns the quantizer that is described by an image header.
    static Quantizer
    fromTableHeader(Header h, int col)
    Returns the quantizer that is described by a binary table header.
    boolean
    isDefault()
    Checks if the quantization is the same as the default quantization.
    double
    toDouble(long value)
    Converts an integer value to the floating-point value it represents under the qunatization.
    long
    toLong(double value)
    Converts a floating point value to its integer representation using the quantization.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Quantizer

      public Quantizer(double scale, double offset, int blankingValue)
      Constructs a new decimal/integer conversion rule.
      Parameters:
      scale - The scaling value, that is the spacing of the qunatized levels
      offset - The floating-point value that corresponds to an integer value of 0 (zero).
      blankingValue - The value to use to represent NaN values in the integer representation, that is missing or invalid data.

    • Quantizer

      public Quantizer(double scale, double offset, Long blankingValue)
      Constructs a new decimal/integer conversion rule.
      Parameters:
      scale - The scaling value, that is the spacing of the qunatized levels
      offset - The floating-point value that corresponds to an integer value of 0 (zero).
      blankingValue - The value to use to represent NaN values in the integer representation, that is missing or invalid data. It may be null if the floating-point data is not expected to contain NaN values ever.

  • Method Details

    • toLong

      public long toLong(double value)
      Converts a floating point value to its integer representation using the quantization.
      Parameters:
      value - the floating point value
      Returns:
      the corresponding qunatized integer value
      See Also:

    • toDouble

      public double toDouble(long value)
      Converts an integer value to the floating-point value it represents under the qunatization.
      Parameters:
      value - the integer value
      Returns:
      the corresponding floating-point value, which may be NaN.
      See Also:

    • isDefault

      public boolean isDefault()
      Checks if the quantization is the same as the default quantization. For example, maybe we don't need to (want to) write the quantization keywords into the FITS headers if these are irrelevant and/or not meaningful. So this method might help us decide when quantization is necessary / meaningful vs when it is irrelevant.
      Returns:
      true if the scaling is 1.0, the offset 0.0, and the blanking value is null. Otherwise false .

    • editImageHeader

      public void editImageHeader(Header h)
      Adds the quantization parameters to an image header,
      Parameters:
      h - the image header.
      See Also:

    • editTableHeader

      public void editTableHeader(Header h, int col)
      Adds the quantization parameters to a binaty table header,
      Parameters:
      h - the binary table header.
      col - the zero-based Java column index
      See Also:

    • fromImageHeader

      public static Quantizer fromImageHeader(Header h)
      Returns the quantizer that is described by an image header.
      Parameters:
      h - an image header
      Returns:
      the quantizer that id described by the header. It may be the default quantizer if the header does not contain any of the quantization keywords.
      See Also:

    • fromTableHeader

      public static Quantizer fromTableHeader(Header h, int col)
      Returns the quantizer that is described by a binary table header.
      Parameters:
      h - a binary table header
      col - the zero-based Java column index
      Returns:
      the quantizer that id described by the header. It may be the default quantizer if the header does not contain any of the quantization keywords.
      See Also: