nom.tam.fits.header.Compression Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of nom-tam-fits Show documentation
Show all versions of nom-tam-fits Show documentation
Java library for reading and writing FITS files. FITS, the Flexible Image Transport System, is the format commonly used in the archiving and transport of astronomical data.
package nom.tam.fits.header;
/*
* #%L
* nom.tam FITS library
* %%
* Copyright (C) 1996 - 2024 nom-tam-fits
* %%
* This is free and unencumbered software released into the public domain.
*
* Anyone is free to copy, modify, publish, use, compile, sell, or
* distribute this software, either in source code form or as a compiled
* binary, for any purpose, commercial or non-commercial, and by any
* means.
*
* In jurisdictions that recognize copyright laws, the author or authors
* of this software dedicate any and all copyright interest in the
* software to the public domain. We make this dedication for the benefit
* of the public at large and to the detriment of our heirs and
* successors. We intend this dedication to be an overt act of
* relinquishment in perpetuity of all present and future rights to this
* software under copyright law.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
* OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
* #L%
*/
/**
* The following keywords are defined by the compression convention for use in the header of the FITS binary table
* extension to describe the structure of the compressed image.
*/
public enum Compression implements IFitsHeader {
/**
* (required keyword) This keyword must have the logical value T. The value field of this keyword shall be ’T’ to
* indicate that the FITS binary table extension contains a compressed BINTABLE, and that logically this extension
* should be interpreted as a tile-compressed binary table.
*/
ZTABLE(VALUE.LOGICAL, "whether this is a compressed table"),
/**
* (required keyword) This keyword must have the logical value T. It indicates that the FITS binary table extension
* contains a compressed image and that logically this extension should be interpreted as an image and not as a
* table.
*/
ZIMAGE(VALUE.LOGICAL, "whether this is a compressed image"),
/**
* (required keyword) The value field of this keyword shall contain a character string giving the name of the
* algorithm that must be used to decompress the image. Currently, values of GZIP 1 , GZIP 2 , RICE 1 , PLIO 1 , and
* HCOMPRESS 1 are reserved, and the corresponding algorithms are described in a later section of this document .
* The value RICE ONE is also reserved as an alias for RICE 1 .
*/
ZCMPTYPE(VALUE.STRING, "compression algorithm"),
/**
* (required keyword) The value field of this keyword shall contain an integer that gives the value of the BITPIX
* keyword in the uncompressed FITS image.
*/
ZBITPIX(VALUE.INTEGER, "original BITPIX value", Standard.BITPIX),
/**
* (required keyword) The value field of this keyword shall contain an integer that gives the value of the NAXIS
* keyword in the uncompressed FITS image.
*/
ZNAXIS(VALUE.INTEGER, "original NAXIS value", Standard.NAXIS),
/**
* (required keywords) The value field of these keywords shall contain a positive integer that gives the value of
* the NAXISn keywords in the uncompressed FITS image.
*/
ZNAXISn(VALUE.INTEGER, "original NAXISn value", Standard.NAXISn),
/**
* (optional keywords) The value of these indexed keywords (where n ranges from 1 to ZNAXIS ) shall contain a
* positive integer representing the number of pixels along axis n of the compression tiles. Each tile of pixels is
* compressed separately and stored in a row of a variable-length vector column in the binary table. The size of
* each image dimension (given by ZNAXISn ) is not required to be an integer multiple of ZTILEn, and if it is not,
* then the last tile along that dimension of the image will contain fewer image pixels than the other tiles. If the
* ZTILEn keywords are not present then the default ’row by row’ tiling will be assumed such that ZTILE1 = ZNAXIS1 ,
* and the value of all the other ZTILEn keywords equals 1. The compressed image tiles are stored in the binary
* table in t he same order that the first pixel in each tile appears in the FITS image; the tile containing the
* first pixel in the image appears in the first row of the table, and the tile containing the last pixel in the
* image appears in the last row of the binary table.
*/
ZTILEn(VALUE.INTEGER, "image tile size along dimension"),
/**
* (optional keywords) These pairs of optional array keywords (where n is an integer index number starting with 1)
* supply the name and value, respectively, of any algorithm-specific parameters that are needed to compress o r
* uncompress the image. The value of ZVALn may have any valid FITS datatype. The order of the compression
* parameters may be significant, and may be defined as part of the description of the specific decompression
* algorithm.
*/
ZNAMEn(VALUE.STRING, "indexed compression parameter name"),
/**
* (optional keywords) These pairs of optional array keywords (where n is an integer index number starting with 1)
* supply the name and value, respectively, of any algorithm-specific parameters that are needed to compress o r
* uncompress the image. The value of ZVALn may have any valid FITS datatype. The order of the compression
* parameters may be significant, and may be defined as part of the description of the specific decompression
* algorithm.
*/
ZVALn(VALUE.ANY, "indexed compression parameter value"),
/**
* (optional keyword) Used to record the name of the image compression algorithm that was used to compress the
* optional null pixel data mask. See the “Preserving undefined pixels with lossy compression” section for more
* details.
*/
ZMASKCMP(VALUE.STRING, "mask compression algorithm"),
/**
* The following optional keyword is defined to store a verbatim copy of the the value and comment field of the
* corresponding keyword in the original uncompressed FITS image. These keywords can be used to reconstruct an
* identical copy of the original FITS file when the image is uncompressed.preserves the original SIMPLE keyword.may
* only be used if the original uncompressed image was contained in the primary array of the FITS file.
*/
ZSIMPLE(VALUE.LOGICAL, "original SIMPLE value", Standard.SIMPLE),
/**
* The following optional keyword is defined to store a verbatim copy of the the value and comment field of the
* corresponding keyword in the original uncompressed FITS image. These keywords can be used to reconstruct an
* identical copy o f the original FITS file when the image is uncompressed.preserves the original XTENSION
* keyword.may only be used if the original uncompressed image was contained in in IMAGE extension.
*/
ZTENSION(VALUE.STRING, "original XTENSION value", Standard.XTENSION),
/**
* The following optional keyword is defined to store a verbatim copy of the the value and comment field of the
* corresponding keyword in the original uncompressed FITS image. These keywords can be used to reconstruct an
* identical copy of the original FITS file when the image is uncompressed.preserves the original EXTEND keyword.may
* only be used if the original uncompressed image was contained in the primary array of the FITS file.
*/
ZEXTEND(VALUE.LOGICAL, "original EXTEND value", Standard.EXTEND),
/**
* The following optional keyword is defined to store a verbatim copy of the the value and comment field of the
* corresponding keyword in the original uncompressed FITS image. These keywords can be used to reconstruct an
* identical copy o f the original FITS file when the image is uncompressed.preserves the original BLOCKED
* keyword.may only be used if the original uncompressed image was contained in the primary array of the FITS file,
*/
@Deprecated
ZBLOCKED(VALUE.LOGICAL, "original BLOCKED value", Standard.BLOCKED),
/**
* The following optional keyword is defined to store a verbatim copy of the the value and comment field of the
* corresponding keyword in the original uncompressed FITS image. These keywords can be used to reconstruct an
* identical copy o f the original FITS file when the image is uncompressed.preserves the original PCOUNT
* keyword.may only be used if the original uncompressed image was contained in in IMAGE extension.
*/
ZPCOUNT(VALUE.INTEGER, "original PCOUNT value", Standard.PCOUNT),
/**
* The following optional keyword is defined to store a verbatim copy of the the value and comment field of the
* corresponding keyword in the original uncompressed FITS image. These keywords can be used to reconstruct an
* identical copy o f the original FITS file when the image is uncompressed.preserves the original GCOUNT
* keyword.may only be used if the original uncompressed image was contained in in IMAGE extension.
*/
ZGCOUNT(VALUE.INTEGER, "original GCOUNTvalue", Standard.GCOUNT),
/**
* The following optional keyword is defined to store a verbatim copy of the the value and comment field of the
* corresponding keyword in the original uncompressed FITS image. These keywords can be used to reconstruct an
* identical copy o f the original FITS file when the image is uncompressed.preserves the original CHECKSUM keyword.
*/
ZHECKSUM(VALUE.STRING, "original CHECKSUM string", Checksum.CHECKSUM),
/**
* The following optional keyword is defined to store a verbatim copy of the the value and comment field of the
* corresponding keyword in the original uncompressed FITS image. These keywords can be used to reconstruct an
* identical copy o f the original FITS file when the image is uncompressed.preserves the original DATASUM
*/
ZDATASUM(VALUE.STRING, "original DATASUM value", Checksum.DATASUM),
/**
* (optional keyword) This keyword records the name of the algorithm that was used to quantize floating-point image
* pixels into integer values which are then passed to the compression algorithm.
*/
ZQUANTIZ(VALUE.STRING, "compression quantization algorithm"),
/**
* (optional keyword) The value field of this keyword shall contain an integer that gives the seed value for the
* random dithering pattern that was used when quantizing the floating-point pixel values. The value may range from
* 1 to 100.00, inclusive.
*/
ZDITHER0(VALUE.INTEGER, "dither algorithm seed value"),
/**
* When using the quantization method to compress floating-point images, this header is used to store the integer
* value that represents undefined pixels (if any) in the scaled integer pixel values. These pixels have an IEEE NaN
* value (Not a Number) in the uncompressed floating-point image. The recommended value for ZBLANK is -2147483648
* (the largest negative 32-bit integer).
*/
ZBLANK(VALUE.INTEGER, "original BLANK value"),
/**
* Stores the original heap offset of the uncompressed heap.
*
* @since 1.19.1
*/
ZTHEAP(VALUE.INTEGER, "original THEAP value", Standard.THEAP),
/**
* The value field of this keyword shall contain an integer representing the number of rows of data from the
* original binary table that are contained in each tile of the compressed table. The number of rows in the last
* tile may be less than in the previous tiles. Note that if the entire table is compressed as a single tile, then
* the compressed table will only contains a single row, and the ZTILELEN and ZNAXIS2 keywords will have the same
* value.
*/
ZTILELEN(VALUE.INTEGER, "number of rows compressed per tile"),
/**
* The value field of these keywords shall contain the character string values of the corresponding TFORMn keywords
* that defines the data type of column n in the original uncompressed FITS table.
*/
ZFORMn(VALUE.STRING, "compressed column data format", Standard.TFORMn),
/**
* The value field of these keywords shall contain a charac- ter string giving the mnemonic name of the algorithm
* that was used to compress column n of the table. The current allowed values are GZIP_1, GZIP_2, and RICE_1, and
* the corresponding algorithms
*/
ZCTYPn(VALUE.STRING, "original CTYPEn");
/**
* This is the simplest option in which no dithering is performed. The floating-point pixels are simply quantized
* using Eq. 1. This option should be assumed if the ZQUANTIZ keyword is not present in the header of the compressed
* floating-point image.
*/
public static final String ZQUANTIZ_NO_DITHER = "NO_DITHER";
/**
* It should be noted that an image that is quantized using this technique can stil l be unquantized using the
* simple linear scaling function given by Eq. 1. The only side effect in this ca se is to introduce slightly more
* noise in the image than if the full subtractive dithering algorith m were applied.
*/
public static final String ZQUANTIZ_SUBTRACTIVE_DITHER_1 = "SUBTRACTIVE_DITHER_1";
/**
* This dithering algorithm is identical to the SUBTRACTIVE DITHER 1 algorithm described above, ex- cept that any
* pixels in the floating-point image that are equa l to 0.0 are represented by the reserved value -2147483647 in
* the quantized integer array. When the i mage is subsequently uncompressed and unscaled, these pixels are restored
* to their original va lue of 0.0. This dithering option is useful if the zero-valued pixels have special
* significance to the da ta analysis software, so that the value of these pixels must not be dithered.
*/
public static final String ZQUANTIZ_SUBTRACTIVE_DITHER_2 = "SUBTRACTIVE_DITHER_2";
/**
* Gzip is the compression algorithm used in the free GN U software utility of the same name. It was created by
* Jean-loup Gailly and Mark Adler and is based on the DEFLATE algorithm, which is a combination of LZ77 and Huffman
* coding. DEFLATE was intended as a replacement for LZW and other patent-encumbered data compression algor ithms
* which, at the time, limited the usability of compress and other popular archivers. Furt her information about
* this compression technique is readily available on the Internet. The gzip alg orithm has no associated parameters
* that need to be specified with the ZNAMEn and ZVALn keywords.
*/
public static final String ZCMPTYPE_GZIP_1 = "GZIP_1";
/**
* If ZCMPTYPE = ’GZIP 2’ then the bytes in the array of image pixel values are shuffled in to decreasing order of
* significance before being compressed with the gzip algorithm. In other words, bytes are shuffled so that the most
* significant byte of every pixel occurs first, in order, followed by the next most significant byte, and so on for
* every byte. Since the most significan bytes of the pixel values often have very similar values, grouping them
* together in this way often achieves better net compression of the array. This is usually especially effective
* when compressing floating-point arrays.
*/
public static final String ZCMPTYPE_GZIP_2 = "GZIP_2";
/**
* If ZCMPTYPE = ’RICE 1’ then the Rice algorithm is used to compress and uncompress the image pixels. The Rice
* algorithm (Rice, R. F., Yeh, P.-S., and Miller, W. H. 1993, in Proc. of the 9th AIAA Computing in Aerospace
* Conf., AIAA-93-4541-CP, American Institute of Aeronautics and Astronautics) is simple and very fast, compressing
* or decompressing 10 7 pixels/sec on modern workstations. It requires only enough memory to hold a single block of
* 16 or 32 pixels at a time. It codes the pixels in small blocks and so is able to adapt very quickly to changes in
* the input image statistics (e.g., Rice has no problem handling cosmic rays, bright stars, saturated pixels,
* etc.).
*/
public static final String ZCMPTYPE_RICE_1 = "RICE_1";
/**
* If ZCMPTYPE = ’PLIO 1’ then the IRAF PLIO (Pixel List) algorithm is used to compress and uncompress the image
* pixels. The PLIO algorithm was developed to store integer-valued image masks in a compressed form. Typical uses
* of image masks are to segment images into regions, or to mark bad pixels. Such masks often have large regions of
* constant value hence are highly compressible. The compression algorithm used is based on run-length encoding,
* with the ability to dynamically follow level changes in the image, allowing a 16-bit encoding to be used
* regardless of the image depth. The worst case performance occurs when successive pixels have different values.
* Even in this case the encoding will only require one word (16 bits) per mask pixel, provided either the delta
* intensity change between pixels is usually less than 12 bits, or the mask represents a zero floored step function
* of constant height. The worst case cannot exceed npix*2 words provided the mask depth is 24 bits or less.
*/
public static final String ZCMPTYPE_PLIO_1 = "PLIO_1";
/**
* Hcompress is an the image compression package written by Richard L. White for use at the Space Telescope Science
* Institute. Hcompress was used to compress the STScI Digitized Sky Survey and has also been used to compress the
* preview images in the Hubble Data Archive. Briefly, the method used is:
* 1. a wavelet transform called the H-transform (a Haar transform generalized to two dimensions), followed by
* 2. quantization that discards noise in the image while retaining the signal on all scales, followed by 10
* 3. quadtree coding of the quantized coefficients.
* The technique gives very good compression for astronomical images and is relatively fast. The calculations are
* carried out using integer arithmetic and a re entirely reversible. Consequently, the program can be used for
* either lossy or lossless compression , with no special approach needed for the lossless case (e.g. there is no
* need for a file of residuals .)
*/
public static final String ZCMPTYPE_HCOMPRESS_1 = "HCOMPRESS_1";
/**
* alternative name for 'RICE 1'
*/
public static final String ZCMPTYPE_RICE_ONE = "RICE_ONE";
/**
* compression algorithm that specifies that the data is uncompressed.
*/
public static final String ZCMPTYPE_NOCOMPRESS = "NOCOMPRESS";
/**
* Each row of this variable-length column contains the byte st ream that is generated as a result of compressing
* the corresponding image tile. The datatype o f the column (as given by the TFORMn keyword) will generally be
* either ’1PB’, ’1PI’ , or ’1PJ’ (or the equivalent ’1Q’ format), depending on whether the compression algorithm ge
* nerates an output stream of 8-bit bytes, 16-bit integers, or 32-bit integers, respectively.
*/
public static final String COMPRESSED_DATA_COLUMN = "COMPRESSED_DATA";
/**
* When using the quantization method to compress floating-poi nt images that is described in Section 4, it
* sometimes may not be possible to quantize some o f the tiles (e.g., if the range of pixels values is too large or
* if most of the pixels have the sam e value and hence the calculated RMS noise level in the tile is close to
* zero). There also may be other rare cases where the nominal compression algorithm can not be applied to certain
* tiles. In these cases, one may use an alternate technique in which the raw pixel values are loss lessly
* compressed with the GZIP algorithm and the resulting byte stream is stored in the GZIP COMPRESSED DATA column
* (with a ’1PB’ or ’1QB’ variable-length array column format). The corresponding COMPRESSED DATA column for these
* tiles must contain a null pointer.
*/
public static final String GZIP_COMPRESSED_DATA_COLUMN = "GZIP_COMPRESSED_DATA";
/**
* Use of this column is no longer recommended, but it may exist i n older compressed image files that were created
* before support for the GZIP COMPRESSED DATA column (describe above) was added to this convention in May 2011.
* This variable length co lumn contains the uncompressed pixels for any tiles that cannot be compressed with the
* norma l method.
*/
public static final String UNCOMPRESSED_DATA_COLUMN = "UNCOMPRESSED_DATA";
/**
* When using the quantization method to compress floating-point images that is described in Section 4, this column
* is used to store the integer value that represents undefined pixels (if any) in the scaled integer pixel values.
* These pixels have an IEEE NaN value (Not a Number) in the uncompressed floating-point image. The recommended
* value for ZBLANK is -2147483648 (the largest negative 32-bit integer).
*/
public static final String ZBLANK_COLUMN = "ZBLANK";
/**
* name of the column containing the quant zero value.
*/
public static final String ZZERO_COLUMN = "ZZERO";
/**
* name of the column containing the quant scale value.
*/
public static final String ZSCALE_COLUMN = "ZSCALE";
/**
*
* The null pixels in integer images are flagged by a reserved BLANK value and will be preserved if a lossless
* compression algorithm is used. If the image is compressed with a lossy algorithm, however (e.g., H-Compress with
* a scale factor greater than 1), then some other technique must be used to identify the null pixels in the image.
*
*
* The recommended method of recording the null pixels when a lossy compression algorithm is used is to create an
* integer data mask with the same dimensions as the image tile. Set the null pixels to 1 and all the other pixels
* to 0, then compress the mask array using a lossless algorithm such as PLIO or GZIP. Store the compressed byte
* stream in a variable-length array column called ’NULL PIXEL MASK’ in the row corresponding to that image tile.
* The ZMASKCMP keyword should be used to record the name of the algorithm used to compress the data mask (e.g.,
* RICE 1). The data mask array pixels will be assumed to have the shortest integer datatype that is supported by
* the compression algorithm (i.e., usually 8-bit bytes).
*
*
* When uncompressing the image tile, the software must check if the corresponding compressed data mask exists with
* a length greater than 0, and if so, then uncompress the mask and set the corresponding undefined pixels in the
* image array to the appropriate value (as given by the BLANK keyword).
*
*/
public static final String NULL_PIXEL_MASK_COLUMN = "NULL_PIXEL_MASK_COLUMN";
/**
* The number of 8-bit bytes in each original integer pixel value.
*/
public static final String BYTEPIX = "BYTEPIX";
/**
* The blocksize parameter for the rise algorithm.
*/
public static final String BLOCKSIZE = "BLOCKSIZE";
/**
* The integer scale parameter determines the amount of compression. Scale = 0 or 1 leads to lossless compression,
* i.e. the decompressed image has exactly the same pixel values as the original image. If the scale factor is
* greater than 1 then the compression is lossy: the decompressed image will not be exactly the same as the
* original.
*/
public static final String SCALE = "SCALE";
/**
* At high compressions factors the decompressed image begins to appear blocky because of the way information is
* discarded. This blockiness is greatly reduced, producing more pleasing images, if the image is smoothed slightly
* during decompression. When done properly, the smoothing will not affect any quantitative photometric or
* astrometric measurements derived from the compressed image. Of course, the smoothing should never be applied when
* the image has been losslessly compressed with a scale factor (defined above) of 0 or 1.
*/
public static final String SMOOTH = "SMOOTH";
private final FitsKey key;
private final IFitsHeader uncompressedKey;
Compression(VALUE valueType, String comment) {
this(valueType, comment, null);
}
Compression(VALUE valueType, String comment, IFitsHeader uncompressedKey) {
key = new FitsKey(name(), IFitsHeader.SOURCE.INTEGRAL, HDU.BINTABLE, valueType, comment);
this.uncompressedKey = uncompressedKey;
FitsKey.registerStandard(this);
}
@Override
public final FitsKey impl() {
return key;
}
/**
* Returns the equivalent of this comression keyword in the uncompressed HDU. For example, the compression keyword
* ZBITPIX that stores the data type of the compressed image will return BITPIX.
*
* @return the equivalent keyword in the uncompressed HDU
*/
public IFitsHeader getUncompressedKey() {
return uncompressedKey;
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy