Class Compression

Object
Compression
All Implemented Interfaces:
Serializable
public final class Compression extends Object implements Serializable
The compression method used for writing GeoTIFF files. This class specifies only the compressions supported by the Apache SIS writer. The Apache SIS reader supports more compression methods, but they are not listed in this class.

The compression to use can be specified as an option when opening the data store. For example for writing a TIFF file without compression, the following code can be used:

var file = Path.of("my_output_file.tiff");
var connector = new StorageConnector(file);
connector.setOption(Compression.OPTION_KEY, Compression.NONE);
try (GeoTiffStore ds = new GeoTiffStore(null, connector)) {
    // Write data here.
}
If no compression is explicitly specified, Apache SIS uses by default the DEFLATE compression.
Since:
1.5
See Also:

  • Field Details

    • NONE

      public static final Compression NONE
      No compression, but pack data into bytes as tightly as possible.

    • DEFLATE

      public static final Compression DEFLATE
      Deflate compression (like ZIP format) with a default compression level and a default predictor. This is the compression used by default by the Apache SIS GeoTIFF writer.

      Predictors

      The compression ratio can sometime be improved by the use of a predictor. For example instead of specifying DEFLATE directly to the Storage­Connector options, the following can be specified: 
      Compression.DEFLATE.withPreductor(BaselineTIFFTagSet.PREDICTOR_HORIZONTAL_DIFFERENCING);
      Whether the use of predictor improves or not the compression ratio depends on the image content. Predictors can help a lot on "smooth" images, but can also be counter-productive on heterogeneous images. The current Apache SIS version uses no predictor by default, but a future SIS version may try to detect automatically whether a predictor should be used. If a deterministic predictor is desired, then with­Predictor(int) should be invoked explicitly.
      See Also:
      "TODO:"
      Compute Shannon Entropy with and without predictor on a few sample rows for deciding automatically which predictor to use.

    • OPTION_KEY

      public static final OptionKey<Compression> OPTION_KEY
      The key for declaring the compression at store creation time. See class Javadoc for usage example.
      See Also:

  • Method Details

    • withLevel

      public Compression withLevel(int value)
      Returns an instance with the specified compression level. The value can range from 1 to 9 inclusive. A value of 0 returns NONE. A value of -1 resets the default compression. This method does nothing if this compression does not support compression levels.
      Parameters:
      value - the new compression level (0-9), or -1 for the default compression.
      Returns:
      a compression of the specified level.
      Throws:
      Illegal­Argument­Exception - if the given value is not in the expected range.
      See Also:

    • level

      public OptionalInt level()
      Returns the current compression level. The returned value is between 0 and 9 inclusive.
      Returns:
      the current compression level, or an empty value for the default level.

    • withPredictor

      public Compression withPredictor(int value)
      Returns an instance with the specified predictor. A predictor is a mathematical operator that is applied to the image data before an encoding scheme is applied. Predictors sometime improve the result of some compression algorithms such as DEFLATE.

      The given predictor may be ignored if it is unsupported by this compression. For example invoking this method on NONE has no effect.

      Parameters:
      value - one of the PREDICTOR_* constants in
      invalid reference 
      Baseline­TIFFTag­Set
      .
      Returns:
      a compression using the specified predictor.
      Throws:
      Illegal­Argument­Exception - if the given value is not valid.
      See Also:
      • invalid reference 
        Baseline­TIFFTag­Set#PREDICTOR_NONE
      • invalid reference 
        Baseline­TIFFTag­Set#PREDICTOR_HORIZONTAL_DIFFERENCING

    • predictor

      public OptionalInt predictor()
      Returns the current predictor. The returned value is one of the PREDICTOR_* constants defined in
      invalid reference 
      Baseline­TIFFTag­Set
      .
      Returns:
      one of the PREDICTOR_* constants, or empty if predictor does not apply to this compression.

    • equals

      public boolean equals(Object other)
      Compares this compression with the given object for equality.
      Overrides:
      equals in class Object
      Parameters:
      other - the object to compare with this compression.
      Returns:
      whether the two objects are equal.

    • hashCode

      public int hashCode()
      Returns a hash code value for this compression.
      Overrides:
      hash­Code in class Object
      Returns:
      a hash code value.

    • toString

      public String toString()
      Returns a string representation of this compression.
      Overrides:
      to­String in class Object
      Returns:
      a string representation for debugging purposes.