Package nom.tam.fits.compression.algorithm.quant

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:

  • 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) data in the quantized representation.
    double
    getBScale()
    Returns the quantization level.
    double
    getBZero()
    Returns the quantization offset.
    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()
    Returns the floating-point value that indicates a null datum in the image before quantization is applied.
    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.
    boolean
    isCheckNull()
    Whether the floating-point data may contain null values (normally NaNs).
    boolean
    isCheckZero()
    Whether automatic quantization treats 0.0 as a special value.
    boolean
    isDither()
    Whether dithering is enabled
    boolean
    isDither2()
    Whether dither method 2 is used.
    boolean
    isLossyCompression()
    Checks if this type of compression is inherently lossy
    ICompressOption
    setBNull(Integer blank)
    Sets the integer value that represents missing data (null) in the quantized representation.
    QuantizeOption
    setBScale(double value)
    Sets the quantization level.
    QuantizeOption
    setBZero(double value)
    Sets the quantization offset.
    QuantizeOption
    setCenterOnZero(boolean value)
    Enabled or disables keeping `BZERO` at 0 when using automatic quantization.
    QuantizeOption
    setCheckNull(boolean value)
    Deprecated.
    setBNull(Integer) controls this feature automatically as needed.
    QuantizeOption
    setCheckZero(boolean value)
    Deprecated.
    It is strongly discouraged to treat 0.0 values as special.
    QuantizeOption
    setDither(boolean value)
    Enables or disables dithering.
    QuantizeOption
    setDither2(boolean value)
    Sets whether dithering is to use method 2.
    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

    Methods inherited from class java.lang.Object

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

  • 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) data in the quantized representation.
      Returns:
      the integer blanking value (null value).
      See Also:

    • getBScale

      public double getBScale()
      Returns the quantization level.
      Returns:
      the floating-point difference between integer levels in the quantized data.
      See Also:

    • getBZero

      public double getBZero()
      Returns the quantization offset.
      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

      public double getNullValue()
      Returns the floating-point value that indicates a null datum 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

      public final Integer getNullValueIndicator()
      Deprecated.
      use getBNull() instead (duplicate method). Returns the integer value that represents missing data (null) in the quantized representation.
      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 `BZERO` at 0 when quantizing automatically.
      See Also:

    • isCheckNull

      public boolean isCheckNull()
      Whether the floating-point data may contain null values (normally NaNs).
      Returns:
      true if we should expect null in the floating-point data. This is automatically true if setBNull(Integer) was called with a non-null value.
      See Also:

    • isCheckZero

      public boolean isCheckZero()
      Whether automatic quantization treats 0.0 as a special value. Normally values within the `BSCALE` quantization level around 0.0 will be assigned the same integer quanta, and will become indistinguishable in the quantized data. Some software may, in their misguided ways, assign exact zero values a special meaning (such as no data) in which case we may want to distinguish these as we apply quantization. However, it is generally not a good idea to use 0 as a special value.
      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 dither method 2 is used.
      Returns:
      true if dither method 2 is used, 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 ICompressOption setBNull(Integer blank)
      Sets the integer value that represents missing data (null) in the quantized representation.
      Parameters:
      blank - the new integer blanking value (that is one that denotes a missing or null datum). Setting this option to null disables the treatment of issing or null data.
      Returns:
      itself
      See Also:

    • setBScale

      public QuantizeOption setBScale(double value)
      Sets the quantization level.
      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.
      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 `BZERO` at 0 when using automatic quantization.
      Parameters:
      value - true to keep `BZERO` 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

      public QuantizeOption setCheckNull(boolean value)
      Deprecated.
      setBNull(Integer) controls this feature automatically as needed. Sets whether we should expect the floating-point data to contain null values (normally NaNs).
      Parameters:
      value - true if the floating-point data may contain null values.
      Returns:
      itself
      See Also:

    • setCheckZero

      public QuantizeOption setCheckZero(boolean value)
      Deprecated.
      It is strongly discouraged to treat 0.0 values as special. FITS only recognises NaN as a special floating-point value marking missing data. All other floating point values are considered valid measurements.
      Sets whether automatic quantization is to treat 0.0 as a special value. Normally values within the `BSCALE` quantization level around 0.0 will be assigned the same integer quanta, and will become indistinguishable in the quantized data. However some software may assign exact zero values a special meaning (such as no data) in which case we may want to distinguish these as we apply qunatization. However, it is generally not a good idea to use 0 as a special value. To mark missing data, the FITS standard recognises only NaN as a special value -- while all other values should constitute valid measurements.
      Parameters:
      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.
      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

      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 to change it. Returns the floating-point value that indicates a null datum 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.
      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.