Oxipng.Options (oxipng v0.1.0)

Copy Markdown View Source

Options for oxipng optimization.

Available Options

  • :level - Optimization preset from 0 to 6 (default: 2).

  • :interlace - Interlacing mode:

    • nil or :keep (default) - Keep original interlacing.
    • true - Request interlacing (Adam7).
    • false - Request removal of interlacing.

    Changes can be skipped if output is not smaller. Set force: true to apply the requested interlacing even without a size improvement.

  • :strip - Metadata stripping:

    • :none or false (default) - Disable optional metadata stripping.
    • :safe or true - Use oxipng's metadata allowlist: cICP, iCCP, sRGB, pHYs, acTL, fcTL, and fdAT. This removes gAMA and cHRM and can affect image appearance.
    • :all - Strip all optional metadata including color profiles.
    • {:keep, list} - Keep only specific chunk names (e.g. {:keep, ["tEXt", "iTXt"]}).
    • {:strip, list} - Strip specific chunk names (e.g. {:strip, ["iCCP"]}).

  • :optimize_alpha - Allow transparency color values to be altered to improve compression when fully transparent (default: false).

  • :bit_depth_reduction - Attempt bit depth reduction (default: true).

  • :color_type_reduction - Attempt color type reduction (default: true).

  • :palette_reduction - Attempt palette reduction (default: true).

  • :grayscale_reduction - Attempt grayscale reduction (default: true).

  • :idat_recoding - Recode IDAT chunks (default: true). Reductions can require recoding even when this is false.

  • :scale_16 - Allow lossy scaling from 16-bit to 8-bit when bit depth reduction is enabled (default: false).

  • :fast_evaluation - Whether to use fast evaluation to pick the best filter (default: nil, uses preset default).

  • :force - Return or write output even if it is not smaller than input (default: false).

  • :fix_errors - Attempt to fix errors when decoding rather than failing (default: false).

  • :timeout - Soft optimization budget in milliseconds (default: nil). Skips further work after the deadline; does not interrupt compression already running, so the call can take longer.

  • :max_decompressed_size - Maximum decompressed size of input in bytes (default: nil).

  • :deflater - DEFLATE algorithm:

    • {:libdeflater, 0..12} - Use libdeflater with compression level.
    • :zopfli - Use Zopfli with default 15 iterations.
    • {:zopfli, iterations} - Use Zopfli with specified iteration count.
    • {:zopfli, iterations, without_improvement} - Use Zopfli with iteration limits.

  • :filters - List of filter strategies to try:

    • Any combination of :none, :sub, :up, :average, :paeth, :min_sum, :entropy, :bigrams, :big_ent, or {:brute, num_lines, level}.

  • :preserve_attrs - In file optimization, preserve file permissions and modification time, but not access time (default: false).

Summary

Types

deflater_opt()
filter_opt()
interlace()
level()
strip_mode()
t()

Functions

new(opts)

Builds and validates an %Oxipng.Options{} struct from a keyword list or map.

new!(opts)

Same as new/1 but raises ArgumentError on invalid options.

to_nif_map(opts)

Converts an %Oxipng.Options{} struct into a map suitable for the NIF.

Types

deflater_opt()

@type deflater_opt() ::
  nil
  | :zopfli
  | {:libdeflater, 0..12}
  | {:zopfli, pos_integer()}
  | {:zopfli, pos_integer(), pos_integer()}

filter_opt()

@type filter_opt() ::
  :none
  | :sub
  | :up
  | :average
  | :paeth
  | :min_sum
  | :entropy
  | :bigrams
  | :big_ent
  | {:brute, pos_integer(), 1..12}

interlace()

@type interlace() :: nil | :keep | boolean()

level()

@type level() :: 0..6

strip_mode()

@type strip_mode() ::
  :none
  | :safe
  | :all
  | boolean()
  | {:keep, [String.t() | atom()]}
  | {:strip, [String.t() | atom()]}

t()

@type t() :: %Oxipng.Options{
  bit_depth_reduction: boolean(),
  color_type_reduction: boolean(),
  deflater: deflater_opt(),
  fast_evaluation: boolean() | nil,
  filters: [filter_opt()] | nil,
  fix_errors: boolean(),
  force: boolean(),
  grayscale_reduction: boolean(),
  idat_recoding: boolean(),
  interlace: interlace(),
  level: level(),
  max_decompressed_size: pos_integer() | nil,
  optimize_alpha: boolean(),
  palette_reduction: boolean(),
  preserve_attrs: boolean(),
  scale_16: boolean(),
  strip: strip_mode(),
  timeout: pos_integer() | nil
}

Functions

new(opts)

@spec new(term()) :: {:ok, t()} | {:error, String.t()}

Builds and validates an %Oxipng.Options{} struct from a keyword list or map.

new!(opts)

@spec new!(term()) :: t()

Same as new/1 but raises ArgumentError on invalid options.

to_nif_map(opts)

@spec to_nif_map(t()) :: map()

Converts an %Oxipng.Options{} struct into a map suitable for the NIF.