Package nom.tam.image.compression.hdu

Class CompressedImageHDU

java.lang.Object
nom.tam.fits.BasicHDU<T>
nom.tam.fits.TableHDU<BinaryTable>
nom.tam.fits.BinaryTableHDU
nom.tam.image.compression.hdu.CompressedImageHDU
All Implemented Interfaces:
FitsElement
public class CompressedImageHDU extends BinaryTableHDU

A header-data unit (HDU) containing a compressed image. A compressed image is a normal binary table with some additional constraints. The original image is divided into tiles and each tile is compressed on its own. The compressed data is then stored in the 3 data columns of this binary table (compressed, gzipped and uncompressed) depending on the compression type used in the tile. Additional data columns may contain specific compression or quantization options for each tile (i.e. compressed table row) individually. Table keywords, which conflict with those in the original image are 'saved' under standard alternative names, so they may be restored with the image as appropriate.

Compressing an image HDU is typically a multi-step process:

  1. Create a CompressedImageHDU, e.g. with fromImageHDU(ImageHDU, int...).
  2. Set up the compression algorithm, including quantization (if desired) via setCompressAlgorithm(String) and setQuantAlgorithm(String), and optionally the compressiomn method used for preserving the blank values via preserveNulls(String).
  3. Set compression (and quantization) options, via calling on getCompressOption(Class)
  4. Perform the compression via compress()

For example to compress an image HDU: 

   ImageHDU image = ...
   
   // 1. Create compressed HDU
   CompressedImageHDU compressed = CompressedImageHDU.fromImageHDU(image, 60, 40);
   
   // 2. Set compression (and optional qunatizaiton) algorithm(s)
   compressed.setCompressAlgorithm(Compression.ZCMPTYPE_RICE_1)
             .setQuantAlgorithm(Compression.ZQUANTIZ_SUBTRACTIVE_DITHER_1)
             .preserveNulls(Compression.ZCMPTYPE_HCOMPRESS_1);
             
   // 3. Set compression (and quantizaiton) options
   compressed.getCompressOption(RiceCompressOption.class).setBlockSize(32);
   compressed.getCompressOption(QuantizeOption.class).setBZero(3.0).setBScale(0.1).setBNull(-999);
                    
   // 4. Perform the compression.
   compressed.compress();

After the compression, the compressed image HDU can be handled just like any other HDU, and written to a file or stream, for example.

The reverse process is simply via the asImageHDU() method. E.g.: 

    CompressedImageHDU compressed = ...
    ImageHDU image = compressed.asImageHDU();
See Also:

  • Field Details

    • MAX_NAXIS_ALLOWED

      public static final int MAX_NAXIS_ALLOWED
      The maximum number of table columns FITS supports
      See Also:

  • Constructor Details

    • CompressedImageHDU

      public CompressedImageHDU(Header hdr, CompressedImageData datum)
      Creates an new compressed image HDU with the specified header and compressed data.
      Parameters:
      hdr - the header
      datum - the compressed image data. The data may not be actually compressed at this point, int which case you may need to call compress() before writing the new compressed HDU to a stream.
      See Also:

  • Method Details

    • fromImageHDU

      public static CompressedImageHDU fromImageHDU(ImageHDU imageHDU, int... tileAxis) throws FitsException
      Prepare a compressed image hdu for the specified image. the tile axis that are specified with -1 default to tiling by rows. To actually perform the compression, you will next have to select the compression algorithm (and optinally a quantization algorithm), then configure options for these, and finally call compress() to perform the compression. See the description of this class for more details.
      Parameters:
      imageHDU - the image to compress
      tileAxis - the requested tile sizes in pixels in x, y, z... order (i.e. opposite of the Java array indexing order!). The actual tile sizes that are set might be different, e.g. to fit within the image bounds and/or to conform to tiling conventions (esp. in more than 2 dimensions).
      Returns:
      the prepared compressed image hdu.
      Throws:
      FitsException - if the image could not be used to create a compressed image.
      See Also:

    • isHeader

      @Deprecated public static boolean isHeader(Header hdr)
      Deprecated.
      (for internal use) Will reduce visibility in the future
      Check that this HDU has a valid header for this type.
      Parameters:
      hdr - header to check
      Returns:
      true if this HDU has a valid header.

    • manufactureData

      @Deprecated public static CompressedImageData manufactureData(Header hdr) throws FitsException
      Deprecated.
      (for internal use) Will reduce visibility in the future
      Returns an empty compressed image data object based on its description in a FITS header.
      Parameters:
      hdr - the FITS header containing a description of the compressed image
      Returns:
      an empty compressed image data corresponding to the header description.
      Throws:
      FitsException - if the header does not sufficiently describe a compressed image

    • asImageHDU

      public ImageHDU asImageHDU() throws FitsException
      Restores the original image HDU by decompressing the data contained in this compresed image HDU.
      Returns:
      The uncompressed Image HDU.
      Throws:
      FitsException - If there was an issue with the decompression.
      See Also:

    • getTileHDU

      public ImageHDU getTileHDU(int[] corners, int[] lengths) throws IOException, FitsException, IllegalArgumentException
      Returns an ImageHDU, with the specified decompressed image area. The HDU's header will be adjusted as necessary to reflect the correct size and coordinate system of the image cutout.
      Parameters:
      corners - the location in pixels where the tile begins in the full (uncompressed) image. The number of elements in the array must match the image dimnesion.
      lengths - the size of the tile in pixels. The number of elements in the array must match the image dimnesion.
      Returns:
      a new image HDU containing the selected area of the uncompresed image, including the adjusted header for the selected area,
      Throws:
      IOException - If the tiling operation itself could not be performed
      FitsException - If the compressed image itself if invalid or imcomplete
      IllegalArgumentException - if the tile area is not fully contained inside the uncompressed image or if the lengths are not positive definite.
      Since:
      1.18
      See Also:

    • getImageAxes

      public int[] getImageAxes() throws FitsException
      Given this compressed HDU, get the original (decompressed) axes.
      Returns:
      the dimensions of the axis.
      Throws:
      FitsException - if the axis are configured wrong.
      Since:
      1.18

    • getImageHeader

      public Header getImageHeader() throws HeaderCardException
      Obtain a header representative of a decompressed ImageHDU.
      Returns:
      Header with decompressed cards.
      Throws:
      HeaderCardException - if the card could not be copied
      Since:
      1.18

    • compress

      public void compress() throws FitsException
      Performs the actual compression with the selected algorithm(s) and options. When creating a compressed image HDU, e.g using the fromImageHDU(ImageHDU, int...) method, the HDU is merely prepared but without actually performing the compression to allow the user to configure the algorithm(S) to be used as well as any specific compression (or quantization) options. See details in the class description.
      Throws:
      FitsException - if the compression could not be performed
      See Also:

    • forceNoLoss

      public CompressedImageHDU forceNoLoss(int x, int y, int width, int heigth)
      Specify an area within the image that will not undergo a lossy compression. This will only have affect it the selected compression (including the options) is a lossy compression. All tiles touched by this region will be handled so that there is no loss of any data, the reconstruction will be exact.
      Parameters:
      x - the x position in the image
      y - the y position in the image
      width - the width of the area
      heigth - the height of the area
      Returns:
      this

    • getCompressOption

      public <T extends ICompressOption> T getCompressOption(Class<T> clazz)
      Returns the compression (or quantization) options for a selected compression option class. It is presumed that the requested options are appropriate for the compression and/or quantization algorithm that was selected. E.g., if you called setCompressionAlgorithm(Compression.ZCMPTYPE_RICE_1), then you can retrieve options for it with this method as getCompressOption(RiceCompressOption.class).
      Type Parameters:
      T - The generic type of the compression class
      Parameters:
      clazz - the compression class
      Returns:
      The current set of options for the requested type, or null if there are no options or if the requested type does not match the algorithm(s) selected.
      See Also:

    • getData

      public CompressedImageData getData()
      Description copied from class: BasicHDU
      Returns the data component of this HDU.
      Overrides:
      getData in class BasicHDU<BinaryTable>
      Returns:
      the associated Data object

    • getUncompressedData

      @Deprecated public Buffer getUncompressedData() throws FitsException
      Deprecated.
      (for internal use) There is no reason why this should be exposed to users. Use asImageHDU() instead. Future release may restrict the visibility to private.
      Returns the uncompressed image in serialized form, as it would appear in a stream.
      Returns:
      the buffer containing the serialized form of the uncompressed image.
      Throws:
      FitsException - if the decompression could not be performed.
      See Also:

    • isHeader

      @Deprecated public boolean isHeader()
      Deprecated.
      Description copied from class: BinaryTableHDU
      Check that this HDU has a valid header.
      Overrides:
      isHeader in class BinaryTableHDU
      Returns:
      true if this HDU has a valid header.

    • preserveNulls

      public CompressedImageHDU preserveNulls(String compressionAlgorithm)
      Sets the compression algorithm used for preserving the blank values in the original image even if the compression is lossy. When compression an integer image, a BLANK header should be defined in its header. You should typically use one of the enum values defined in Compression.
      Parameters:
      compressionAlgorithm - compression algorithm to use for the null pixel mask, see Compression for recognized names.
      Returns:
      itself
      See Also:

    • setCompressAlgorithm

      public CompressedImageHDU setCompressAlgorithm(String compressAlgorithm) throws FitsException
      Sets the compression algorithm to use, by its standard FITS name. You should typically use one of the enum values defined in Compression.
      Parameters:
      compressAlgorithm - compression algorithm to use, see Compression for recognized names.
      Returns:
      itself
      Throws:
      FitsException - if no algorithm is available by the specified name
      See Also:

    • setQuantAlgorithm

      public CompressedImageHDU setQuantAlgorithm(String quantAlgorithm) throws FitsException
      Sets the quantization algorithm to use, by its standard FITS name. You should typically use one of the enum values defined in Compression.
      Parameters:
      quantAlgorithm - quantization algorithm to use, see Compression for recognized names.
      Returns:
      itself
      Throws:
      FitsException - if no algorithm is available by the specified name
      See Also: