# 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:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Compression`
  `DEFLATE`
  Deflate compression (like ZIP format) with a default compression level and a default predictor.
  `static final Compression`
  `NONE`
  No compression, but pack data into bytes as tightly as possible.
  `static final OptionKey<Compression>`
  `OPTION_KEY`
  The key for declaring the compression at store creation time.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object other)`
  Compares this compression with the given object for equality.
  `int`
  `hashCode()`
  Returns a hash code value for this compression.
  `OptionalInt`
  `level()`
  Returns the current compression level.
  `OptionalInt`
  `predictor()`
  Returns the current predictor.
  `String`
  `toString()`
  Returns a string representation of this compression.
  `Compression`
  `withLevel(int value)`
  Returns an instance with the specified compression level.
  `Compression`
  `withPredictor(int value)`
  Returns an instance with the specified predictor.

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## 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 `StorageConnector` 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 `withPredictor(int)` should be invoked explicitly.
    See Also:
      - `withPredictor(int)`
    "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:
      - `StorageConnector​.setOption(OptionKey, Object)`

- ## 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:
      `IllegalArgumentException` - if the given value is not in the expected range.
    See Also:
      - `Deflater​.BEST_SPEED`
      - `Deflater​.BEST_COMPRESSION`
      - `Deflater​.NO_COMPRESSION`

  - ### 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

          BaselineTIFFTagSet

      .
    Returns:
      a compression using the specified predictor.
    Throws:
      `IllegalArgumentException` - if the given value is not valid.
    See Also:
      - invalid reference

            BaselineTIFFTagSet#PREDICTOR_NONE

      - invalid reference

            BaselineTIFFTagSet#PREDICTOR_HORIZONTAL_DIFFERENCING

  - ### predictor

    public OptionalInt predictor()
    Returns the current predictor. The returned value is one of the `PREDICTOR_*` constants defined in
    invalid reference

        BaselineTIFFTagSet

    .
    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:
      `hashCode` in class `Object`
    Returns:
      a hash code value.

  - ### toString

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