YOGA Image Command Line Interface

usage: yoga image [-h] [-v] [-q] [--output-format {orig,auto,jpeg,png}]
                  [--resize {orig,<SIZE>,<WIDTH>x<HEIGHT>}] [--jpeg-quality 0-100]
                  [--opacity-threshold 0-255]
                  input output

positional arguments:
  input                 Input file path
  output                Output file path

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         enable verbose mode
  -q, --quiet           enable quiet mode (takes precedence over verbose)
  --output-format {orig,auto,jpeg,png,webp,webpl}
                        format of the output image
  --resize {orig,<SIZE>,<WIDTH>x<HEIGHT>}
                        resize the image
  --jpeg-quality 0-100  JPEG quality if the output format is set to 'jpeg'
  --webp-quality 0-100  WEBP quality if the output format is set to 'webp'
  --opacity-threshold 0-255
                        threshold below which a pixel is considered transparent
  --png-slow-optimization
                        enable a (very) slow optimization preset for PNGs that
                        can sometimes gain few bytes on the output file
  --enable-quantization
                        reduce the number of colors used in the image
  --quantization-dithering-level 0.0-1.0
                        the dithering level to use when
                        --enable-quantization is set
  --quantization-max-colors 1-256
                        the maximum number of colors to use when
                        --enable-quantization is set

Basic Usage

The simplest way to optimize an image is by using the following command:

yoga  image  input.png  output.png

Note

When the output format is not specified, YOGA outputs an image using the same format as the input one (PNG → PNG, JPEG → JPEG, WEBP → WEBP, WEBP (lossless) → WEBP (lossless)).

Only PNGs, JPEGs and WEBPs are supported as input when the output format is not explicitly specified.

Output Format

The output format can be specified using the --output-format option:

yoga  image  --ouput-format=jpeg   input.png  output.jpg

The following formats are supported:

orig: This is the default. The output format will be the same as the one of the input image.
auto: The output format is automatically selected. YOGA will generate a PNG if the input image is using transparency, else it will generate a JPEG.
png: Outputs a PNG image.
jpeg: Outputs a JPEG image.
webp: Outputs a lossy WEBP image.
webpl: Outputs a lossless WEBP image.

Note

When using the "orig" output format, YOGA will only accept PNG, JPEG and WEBP images as input.

Resize Output Image

YOGA allows you to resize images with the --resize option:

yoga  image  --resize=512  input.png  output.png
yoga  image  --resize=512x512  input.png  output.png

Note

If the width and the height have the same value, you do not have to specify both, so 512 and 512x512 are equivalent.

Note

YOGA always preserve the image’s aspect ratio; you can consider the size you provide as a box the image will fit in.

Output JPEG Quality

YOGA allows you to tune the desired quality of the JPEG it outputs with the --jpeg-quality option. This option takes an integer between 0 and 100 as parameter:

0: ugly images but smaller files,
100: best quality images but larger files.

The default JPEG quality is 84%.

yoga  image  --output-format=jpeg  --jpeg-quality=84  input.png  output.jpg

Note

This option has effect only when the output image is a JPEG.

Output WEBP Quality

YOGA allows you to tune the desired quality of the WEBP it outputs with the --webp-quality option. This option takes an integer between 0 and 100 as parameter:

0: ugly images but smaller files,
100: best quality images but larger files.

The default WEBP quality is 90%.

yoga  image  --output-format=webp  --webp-quality=90  input.png  output.webp

Note

This option has effect only when the output image is a lossy WEBP.

Opacity Threshold

YOGA allows you to tune the threshold below which a pixel is considered transparent using the --opacity-threshold option. This option is only useful in addition to --output-format=auto and takes an integer between 0 and 255 as parameter:

0: all pixels are considered transparent,
255: all pixels are considered opaque.

The default value is 254.

yoga  image  --output-format=auto  --opacity-threshold=254  input.png  output.xxx

Slow PNG Optimization

YOGA allows you to select an alternative preset for PNGs optimization. This preset can sometimes gain few bytes over the default one, but it is 10 times slower on average. You will generally not want to enable this.

To enable this preset, use the --png-slow-optimization option:

yoga  image  --png-slow-optimization  input.png  output.png

Color Quantization

Color quantization is an operation that reduces the number of distinct colors used in an image.

To enable the color quantization, use the --enable-quantization option:

yoga  image  --enable-quantization  input.png  output.png

When color quantization is enabled, YOGA will produce images containing at most 256 colors (8-bit). You can control the maximum number of colors with the --quantization-max-colors option. This options takes an integer between 1 and 256 as parameter (256 is the default value):

yoga  image  --enable-quantization  --quantization-max-colors=128  input.png  output.png

By default, YOGA will use dithering to reduce the visual impact of the color loss, but this have an incidence on the efficiency of the compression. You can control the level of the dithering or disable it using the --quantization-dithering-level option, that takes a number between 0.0 and 1.0 as value:

0.0: no dithering
1.0: maximal dithering

The default value is 1.0.

yoga  image  --enable-quantization  --quantization-dithering-level=0.5  input.png  output.png

Here are examples of the effect of the dithering levels:

max-colors	dithering-level	File size
Original image (quantization disabled)		7,2 kB
5	1.0	1.4 kB
5	0.75	1.4 kB
5	0.5	1.2 kB
5	0.25	626 B
5	0.0	180 B

Note

In some cases, like PNG to PNG optimisation, the quantization can be ignored by YOGA if it produces an output image larger that the input one.