Class QuantizeOption

java.lang.Object
nom.tam.fits.compression.algorithm.quant.QuantizeOption
All Implemented Interfaces:
Cloneable, ICompressOption
Direct Known Subclasses:
HCompressorQuantizeOption, RiceQuantizeCompressOption
public class QuantizeOption extends Object implements ICompressOption
Quantization options when they are part of the compression scheme. When compressing tables and images includes quantization (integer representation of floating point data), users can control how exactly the quantization should be performed. When reading compressed FITS files, these options will be set automatically based on the header values recorded in the compressed HDU.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    RECOMMENDED_NAN_INDICATOR
    The integer value recommeded by the FITS standard to represent NaN floating-point values in integer compressed data.

  • Constructor Summary

    Constructors
    Constructor
    Description
    QuantizeOption(ICompressOption compressOption)
    Creates a new set of quantization options, to be used together with the specified compression options.

  • Method Summary

    Modifier and Type
    Method
    Description
    QuantizeOption
    copy()
    Returns an independent copy of this option.
    Integer
    getBNull()
    Returns the integer value that represents missing (null) for integer compressed floating-point data.
    double
    getBScale()
    Returns the quantization level for integer compressed floating-point data.
    double
    getBZero()
    Returns the quantization offset for integer compressed floating-point data.
    nom.tam.fits.compression.provider.param.api.ICompressParameters
    getCompressionParameters()
    (for internal use) Returns the parameters that represent the settings for this option in the FITS header or compressed data column.
    final ICompressOption
    getCompressOption()
    Returns the options for the compression algorithm that accompanies quantization.
    <T> T
    getCompressOption(Class<T> clazz)
    Returns the compression or quantization options, recast for the selected option class.
    int
    getIntMaxValue()
    Returns the maximum integer level in the quantized representation.
    int
    getIntMinValue()
    Returns the maximum integer level in the quantized representation.
    double
    getMaxValue()
    Returns the maximum floating-point value in the data
    double
    getMinValue()
    Returns the minimum floating-point value in the data
    double
    getNullValue()
    Deprecated.
    The FITS standard allows only NaNs to indicate missing / invalid floating-point data.
    final Integer
    getNullValueIndicator()
    Deprecated.
    use getBNull() instead (duplicate method).
    double
    getQLevel()
    Returns the quantization resolution level used for automatic qunatization.
    long
    getSeed()
    Gets the random seed value used for dithering
    int
    getTileHeight()
    Returns the tile height
    long
    getTileIndex()
    Returns the sequential tile index that this option is currently configured for.
    int
    getTileWidth()
    Returns the tile width
    boolean
    isCenterOnZero()
    Checks whether we force the integer quantized level 0 to correspond to a floating-point level 0.0, when using automatic quantization.
    final boolean
    isCheckNull()
    Deprecated.
    Use getBNull() instead to see if a custom null-value indicator has been configured.
    boolean
    isCheckZero()
    Deprecated.
    Use isDither2() instead.
    boolean
    isDither()
    Whether dithering is enabled
    boolean
    isDither2()
    Whether dithering (when enabled) uses method 2, which treats 0.0 values as special.
    boolean
    isLossyCompression()
    Checks if this type of compression is inherently lossy
    static final boolean
    isUseFMA()
    Checks whether Math.fma(double, double, double) is used for converting quantized integers back to doubles.
    QuantizeOption
    setBNull(Integer blank)
    Sets the integer value that represents missing data (null) for integer compressed floating-point data.
    QuantizeOption
    setBScale(double value)
    Sets the quantization level for integer compressed floating-point data.
    QuantizeOption
    setBZero(double value)
    Sets the quantization offset for integer compressed floating-point data.
    QuantizeOption
    setCenterOnZero(boolean value)
    Enabled or disables keeping `ZZERO` at 0 when using automatic quantization.
    QuantizeOption
    setCheckNull(boolean value)
    Deprecated.
    This feature is set automatically as needed.
    QuantizeOption
    setCheckZero(boolean value)
    Deprecated.
    Use setDither2(boolean) instead if you want zero values to be special encoded.
    QuantizeOption
    setDither(boolean value)
    Enables or disables dithering.
    QuantizeOption
    setDither2(boolean value)
    Sets whether dithering is to use method 2, when dithering is enabled.
    QuantizeOption
    setIntMaxValue(int value)
    Sets the maximum integer level in the quantized representation.
    QuantizeOption
    setIntMinValue(int value)
    Sets the minimum integer level in the quantized representation.
    QuantizeOption
    setMaxValue(double value)
    Sets the maximum floating-point value in the data
    QuantizeOption
    setMinValue(double value)
    Sets the minimum floating-point value in the data
    QuantizeOption
    setNullValue(double value)
    Deprecated.
    The use of null values other than NaN for floating-point data types is not standard in FITS.
    void
    setParameters(nom.tam.fits.compression.provider.param.api.ICompressParameters parameters)
    (for internal use) Sets the parameters that link the options to how they are recorded in the FITS headers or compressed table columns.
    QuantizeOption
    setQlevel(double value)
    Sets the quantization resolution level to use for automatic quantization.
    QuantizeOption
    setSeed(long value)
    Sets the seed value for the dither random generator
    QuantizeOption
    setTileHeight(int value)
    Set the tile height (if the option supports it).
    QuantizeOption
    setTileIndex(int index)
    Sets the tile index for which to initialize the random number generator with the given seed (i.e.
    QuantizeOption
    setTileWidth(int value)
    Set the tile width (if the option supports it).
    <T> T
    unwrap(Class<T> clazz)
    (for internal use) Recasts these options for the specific implementation class
    static void
    useFMA(boolean value)
    Selects whether Math.fma(double, double, double) should be used when converting quantized integers back to doubles.

    Methods inherited from class Object

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

  • Field Details

  • Constructor Details

    • QuantizeOption

      public QuantizeOption(ICompressOption compressOption)
      Creates a new set of quantization options, to be used together with the specified compression options.
      Parameters:
      compressOption - Compression-specific options to pair with these quantization options, or null.
      Since:
      1.18

  • Method Details

    • copy

      public QuantizeOption copy()
      Description copied from interface: ICompressOption
      Returns an independent copy of this option. Modifications to the original or the copy will not affect the other.
      Specified by:
      copy in interface ICompressOption
      Returns:
      copy the option (normally the option from with the copy happened is saved as original).

    • getBNull

      public Integer getBNull()
      Returns the integer value that represents missing (null) for integer compressed floating-point data. This funtion was named poorly as it sets the ZBLANK value in the header or in the equivalently named column.
      Returns:
      the integer blanking value (for integer-compressed NaNs). If the returned value is null, then the recommended value -2147483647 will be used as needed.
      See Also:

    • getBScale

      public double getBScale()
      Returns the quantization level for integer compressed floating-point data. This funtion was named poorly as it sets the ZSCALE parameter value in the named column when compressing floating-point data with an algorithm that supports integers only. It has nothing to do with the BSCALE header value, which indicates the integer representation of floating-point data for the uncompressed data.
      Returns:
      the floating-point difference between integer levels in the quantized data.
      See Also:

    • getBZero

      public double getBZero()
      Returns the quantization offset for integer compressed floating-point data. This funtion was named poorly as it sets the ZZERO parameter value in the named column when compressing floating-point data with an algorithm that supports integers only. It has nothing to do with the BZERO header value, which indicates the integer representation of floating-point data for the uncompressed data.
      Returns:
      the floating-point value corresponding to the integer level 0.
      See Also:

    • getCompressionParameters

      public nom.tam.fits.compression.provider.param.api.ICompressParameters getCompressionParameters()
      Description copied from interface: ICompressOption
      (for internal use) Returns the parameters that represent the settings for this option in the FITS header or compressed data column.
      Specified by:
      getCompressionParameters in interface ICompressOption
      Returns:
      the parameters that must be synchronized with the hdu meta data.
      See Also:

    • getCompressOption

      public <T> T getCompressOption(Class<T> clazz)
      Returns the compression or quantization options, recast for the selected option class.
      Type Parameters:
      T - the generic type of the compression option
      Parameters:
      clazz - the option class for the compression algorithm used with the quantization, or QunatizeOption.class for our own options.
      Returns:
      the recast options for the requested class or null id we do not have access to options of the requested class.
      See Also:

    • getCompressOption

      public final ICompressOption getCompressOption()
      Returns the options for the compression algorithm that accompanies quantization.
      Returns:
      the options for the compression algorithm, or null
      See Also:

    • getIntMaxValue

      public int getIntMaxValue()
      Returns the maximum integer level in the quantized representation.
      Returns:
      the maximum integer level in the quantized data.
      See Also:

    • getIntMinValue

      public int getIntMinValue()
      Returns the maximum integer level in the quantized representation.
      Returns:
      the maximum integer level in the quantized data.
      See Also:

    • getMaxValue

      public double getMaxValue()
      Returns the maximum floating-point value in the data
      Returns:
      the maximum floating-point value in the data before quantization.
      See Also:

    • getMinValue

      public double getMinValue()
      Returns the minimum floating-point value in the data
      Returns:
      the minimum floating-point value in the data before quantization.
      See Also:

    • getNullValue

      @Deprecated public double getNullValue()
      Deprecated.
      The FITS standard allows only NaNs to indicate missing / invalid floating-point data.
      Returns the floating-point value that indicates missing or invalid data in the image before quantization is applied. Normally, the FITS standard is that NaN values indicate null values in floating-point images. While this class allows using other values also, they are not recommended since they are not supported by FITS in a standard way.
      Returns:
      the floating-point value that represents a null value (missing data) in the image before quantization.
      See Also:

    • getNullValueIndicator

      @Deprecated public final Integer getNullValueIndicator()
      Deprecated.
      use getBNull() instead (duplicate method). Returns the integer value that represents NaN values in integer-compressed floating-point data.
      Returns:
      the integer blanking value (null value).
      See Also:

    • getQLevel

      public double getQLevel()
      Returns the quantization resolution level used for automatic qunatization. For Gaussian noise the quantization level is the standard deviation of the noise divided by this Q value. Thus Q values of a few will ensure that quantization retains just about all of the information in the noisy data.
      Returns:
      The current Q value, defined as the number of quantized levels per standard deviation (for Gaussian noise).
      See Also:

    • getSeed

      public long getSeed()
      Gets the random seed value used for dithering
      Returns:
      the random seed value used for dithering
      See Also:

    • getTileIndex

      public long getTileIndex()
      Returns the sequential tile index that this option is currently configured for.
      Returns:
      the sequential tile index that the quantization is configured for
      See Also:

    • getTileHeight

      public int getTileHeight()
      Returns the tile height
      Specified by:
      getTileHeight in interface ICompressOption
      Returns:
      the tile height in pixels
      See Also:

    • getTileWidth

      public int getTileWidth()
      Returns the tile width
      Specified by:
      getTileWidth in interface ICompressOption
      Returns:
      the tile width in pixels
      See Also:

    • isCenterOnZero

      public boolean isCenterOnZero()
      Checks whether we force the integer quantized level 0 to correspond to a floating-point level 0.0, when using automatic quantization.
      Returns:
      true if we want to keep `ZZERO` at 0.0 when quantizing automatically.
      See Also:

    • isCheckNull

      @Deprecated public final boolean isCheckNull()
      Deprecated.
      Use getBNull() instead to see if a custom null-value indicator has been configured.
      Whether the floating-point data may contain null values (normally NaNs).
      Returns:
      true (always since 1.23).
      See Also:

    • isCheckZero

      @Deprecated public boolean isCheckZero()
      Deprecated.
      Use isDither2() instead. The special treatent of ero values is the distinghuishing feature of the SUBTRACTIVE_DITHER_2 method, which is otherwise the same as SUBTRACTIVE_DITHER_1.
      Whether automatic quantization treats 0.0 as a special value. The special treatment of 0.0 values is the distinguishing feature of dither method 2 over method 1.
      Returns:
      true to treat 0.0 (exact) as a special value, or false to treat is as any other measured value (recommended).
      See Also:

    • isDither

      public boolean isDither()
      Whether dithering is enabled
      Returns:
      true if dithering is enabled, or else false
      See Also:

    • isDither2

      public boolean isDither2()
      Whether dithering (when enabled) uses method 2, which treats 0.0 values as special.
      Returns:
      true if method 2 is used is used for dithering, or else false
      See Also:

    • isLossyCompression

      public boolean isLossyCompression()
      Description copied from interface: ICompressOption
      Checks if this type of compression is inherently lossy
      Specified by:
      isLossyCompression in interface ICompressOption
      Returns:
      true if the compression done with this specified options uses approximations. That means if the reconstruction of the data is excact the return should be false.

    • setBNull

      public QuantizeOption setBNull(Integer blank)
      Sets the integer value that represents missing data (null) for integer compressed floating-point data. This funtion was named poorly as it sets the ZBLANK value in the header or in the equivalently named column.
      Parameters:
      blank - the new integer value that denotes NaN when floating-point data is compressed with an integer-only algorithm. Setting this option to null will set the header ZBLANK value, when the data contains NaNs, to -2147483647 (i.e., the value recommended by the FITS standard).
      Returns:
      itself
      See Also:

    • setBScale

      public QuantizeOption setBScale(double value)
      Sets the quantization level for integer compressed floating-point data. This funtion was named poorly as it sets the ZZERO parameter value in the named column when compressing floating-point data with an algorithm that supports integers only. It has nothing to do with the BZERO header value, which indicates the integer representation of floating-point data for the uncompressed data.
      Parameters:
      value - the new floating-point difference between integer levels in the quantized data.
      Returns:
      itself
      See Also:

    • setBZero

      public QuantizeOption setBZero(double value)
      Sets the quantization offset for integer compressed floating-point data. This funtion was named poorly as it sets the ZZERO parameter value in the named column when compressing floating-point data with an algorithm that supports integers only. It has nothing to do with the BZERO header value, which indicates the integer representation of floating-point data for the uncompressed data.
      Parameters:
      value - the new floating-point value corresponding to the integer level 0.
      Returns:
      itself
      See Also:

    • setCenterOnZero

      public QuantizeOption setCenterOnZero(boolean value)
      Enabled or disables keeping `ZZERO` at 0 when using automatic quantization.
      Parameters:
      value - true to keep `ZZERO` at 0 when quantizing automatically, that is keep the integer quantized level 0 correspond to floating-point level 0.0. Or, false to let the automatic quantization algorithm determine the optimal quantization offset.
      Returns:
      iftself
      See Also:

    • setCheckNull

      @Deprecated public QuantizeOption setCheckNull(boolean value)
      Deprecated.
      This feature is set automatically as needed.
      Obsolete method that used to set whether we should expect the floating-point data to contain null values (NaNs).
      Parameters:
      value - (unused since 1.23)
      Returns:
      itself
      See Also:

    • setCheckZero

      @Deprecated public QuantizeOption setCheckZero(boolean value)
      Deprecated.
      Use setDither2(boolean) instead if you want zero values to be special encoded. The representation of true zero values is the unique feature of the SUBTRACTIVE_DITHER_2 method that sets it apart from SUBTRACTIVE_DITHER_1.
      Sets whether automatic quantization is to treat 0.0 as a special value. This is the same as setDither2(boolean). When enabled and dithering is used, then 0.0 values will be denoted with the special value −2147483647 in the quantized representation.
      Parameters:
      value - (unused) value whether to treat values around 0.0 as special.
      Returns:
      itself
      See Also:

    • setDither

      public QuantizeOption setDither(boolean value)
      Enables or disables dithering.
      Parameters:
      value - true to enable dithering, or else false to disable
      Returns:
      itself
      See Also:

    • setDither2

      public QuantizeOption setDither2(boolean value)
      Sets whether dithering is to use method 2, when dithering is enabled. It does not actually enable or disable dithering itself -- for that you must call setDither(boolean). When dither method 2 is used, then 0.0 values will be denoted with the special value −2147483647 in the quantized representation, whereas dither method 1 treats 0.0 just like any other decomal value.
      Parameters:
      value - true to use dither method 2, or else false for method 1.
      Returns:
      itself
      See Also:

    • setIntMaxValue

      public QuantizeOption setIntMaxValue(int value)
      Sets the maximum integer level in the quantized representation.
      Parameters:
      value - the new maximum integer level in the quantized data.
      Returns:
      itself
      See Also:

    • setIntMinValue

      public QuantizeOption setIntMinValue(int value)
      Sets the minimum integer level in the quantized representation.
      Parameters:
      value - the new minimum integer level in the quantized data.
      Returns:
      itself
      See Also:

    • setMaxValue

      public QuantizeOption setMaxValue(double value)
      Sets the maximum floating-point value in the data
      Parameters:
      value - the maximum floating-point value in the data before quantization.
      Returns:
      itself
      See Also:

    • setMinValue

      public QuantizeOption setMinValue(double value)
      Sets the minimum floating-point value in the data
      Parameters:
      value - the mininum floating-point value in the data before quantization.
      Returns:
      itself
      See Also:

    • setNullValue

      @Deprecated public QuantizeOption setNullValue(double value)
      Deprecated.
      The use of null values other than NaN for floating-point data types is not standard in FITS. You should therefore avoid using this method, in general.
      Sets the floating-point value that indicates missing data in the floating point image image before quantization is applied. Normally, the FITS standard is that NaN values indicate null values in floating-point images. While this class allows using other values also, they are not recommended since they are not supported by FITS in a standard way.
      Parameters:
      value - the new floating-point value that represents a null value (missing data) in the image before quantization.
      Returns:
      itself
      See Also:

    • setParameters

      public void setParameters(nom.tam.fits.compression.provider.param.api.ICompressParameters parameters)
      Description copied from interface: ICompressOption
      (for internal use) Sets the parameters that link the options to how they are recorded in the FITS headers or compressed table columns.
      Specified by:
      setParameters in interface ICompressOption
      Parameters:
      parameters - the parameters to synchronized
      See Also:

    • setQlevel

      public QuantizeOption setQlevel(double value)
      Sets the quantization resolution level to use for automatic quantization. For Gaussian noise the quantization level is the standard deviation of the noise divided by this Q value. Thus Q values of a few will ensusre that quantization retains just about all of the information contained in the noisy data.
      Parameters:
      value - The new Q value, defined as the number of quantized levels per standard deviation (for Gaussian noise).
      Returns:
      itself
      See Also:

    • setSeed

      public QuantizeOption setSeed(long value)
      Sets the seed value for the dither random generator
      Parameters:
      value - The seed value, as in ZDITHER0, normally a number between 1 and 10000 (inclusive).
      Returns:
      itself
      See Also:

    • setTileIndex

      public QuantizeOption setTileIndex(int index)
      Sets the tile index for which to initialize the random number generator with the given seed (i.e. ZDITHER0 value).
      Parameters:
      index - The 0-based tile index
      Returns:
      itself
      See Also:

    • setTileHeight

      public QuantizeOption setTileHeight(int value)
      Description copied from interface: ICompressOption
      Set the tile height (if the option supports it). If the implementing option class does not have a setting for tile size, it should simply ignore the setting and return normally.
      Specified by:
      setTileHeight in interface ICompressOption
      Parameters:
      value - the new tile height in pixels
      Returns:
      itself
      See Also:

    • setTileWidth

      public QuantizeOption setTileWidth(int value)
      Description copied from interface: ICompressOption
      Set the tile width (if the option supports it). If the implementing option class does not have a setting for tile size, it should simply ignore the setting and return normally.
      Specified by:
      setTileWidth in interface ICompressOption
      Parameters:
      value - the new tile with in pixels
      Returns:
      itself
      See Also:

    • unwrap

      public <T> T unwrap(Class<T> clazz)
      Description copied from interface: ICompressOption
      (for internal use) Recasts these options for the specific implementation class
      Specified by:
      unwrap in interface ICompressOption
      Type Parameters:
      T - these options recast to the designated implementation type.
      Parameters:
      clazz - the implementation class
      Returns:
      the recast version of us or null if the recasting is not available for the specified class type.

    • useFMA

      public static void useFMA(boolean value)
      Selects whether Math.fma(double, double, double) should be used when converting quantized integers back to doubles. Othwerwise normal arithmetic is used, which is the default. CFITSIO and astropy both rely on fma(), which has better precision, but is not supported on some (older) architectures. When hardware support is lacking, you may expect a significant performance hit from the software implementation.
      Parameters:
      value - true to use fma(), or else false to use regular arithmetics.
      Since:
      1.23
      See Also:

    • isUseFMA

      public static final boolean isUseFMA()
      Checks whether Math.fma(double, double, double) is used for converting quantized integers back to doubles.
      Returns:
      true if using fma(), or else false is using regular arithmetics.
      Since:
      1.23