YOGA Image Python API

This module allows to convert and optimize images.

Usage

Converting and optimizing an image:

import yoga.image
yoga.image.optimize("./input.png", "./output.png")

You can also tune the output by passing options:

yoga.image.optimize("./input.png", "./output.png", options={
    "output_format": "orig",         # "orig"|"auto"|"jpeg"|"png"|"webp"|"webpl"
    "resize": "orig",                # "orig"|[width,height]
    "jpeg_quality": 0.84,            # 0.00-1.0
    "webp_quality": 0.90,            # 0.00-1.0
    "opacity_threshold": 254,        # 0-255
    "png_slow_optimization": False,  # True|False
})

Available Options

output_format

The format of the output image.

yoga.image.optimize("./input.png", "./output.png", options={
    "output_format": "orig",
})

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

Resize the output image.

Allowed values are:

"orig": The default. Keeps the original size (no resize).
[width, height]: The box in which the image should fit.

yoga.image.optimize("./input.png", "./output.png", options={
    "resize": "orig",
})

yoga.image.optimize("./input.png", "./output.png", options={
    "resize": [512, 512],
})

Note

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

jpeg_quality

The quality of the output JPEGs.

The value is a number between 0.00 and 1.00 (0.84 by default):

0.00: ugly images but smaller files,
1.00: best quality images but larger files.

yoga.image.optimize("./input.png", "./output.jpg", options={
    "output_format": "jpeg",
    "jpeg_quality": 0.84,
})

Note

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

webp_quality

The quality of the output WEBPs.

The value is a number between 0.00 and 1.00 (0.90 by default):

0.00: ugly images but smaller files,
1.00: best quality images but larger files.

yoga.image.optimize("./input.png", "./output.webp", options={
    "output_format": "webp",
    "webp_quality": 0.90,
})

Note

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

opacity_threshold

The threshold below which a pixel is considered transparent. This option is only useful when output_format is defined to auto.

The value is a number between 0 and 255 (254 by default):

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

yoga.image.optimize("./input.png", "./output.xxx", options={
    "output_format": "auto",
    "opacity_threshold": 254,
})

png_slow_optimization

If True, select a slower optimization preset for PNGs. 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.

yoga.image.optimize("./input.png", "./output.png", options={
    "output_format": "png",
    "png_slow_optimization": False,
})

enable_quantization

If True, YOGA will reduce the number of distinct colors used in the image to 256 colors maximum. By default dithering will be used to reduce the visual impact of the color loss.

The color quantization is disabled by default.

yoga.image.optimize("./input.png", "./output.png", options={
    "enable_quantization": True,
})

See Color Quantization CLI options for more details.

quantization_max_colors

The maximum number of colors to use in the output image. This options has effect only when enable_quantization is set to True.

The value is a number between 1 and 256 (256 by default).

yoga.image.optimize("./input.png", "./output.png", options={
    "enable_quantization": True,
    "quantization_max_colors": 256,
})

See Color Quantization CLI options for more details.

quantization_dithering_level

The maximum dithering level used when reducing image colors. This options has effect only when enable_quantization is set to True.

The value is a number between 0.0 and 1.0 (1.0 by default):

0.0: no dithering
1.0: maximal dithering

yoga.image.optimize("./input.png", "./output.png", options={
    "enable_quantization": True,
    "quantization_dithering_level": 1.0,
})

See Color Quantization CLI options for more details.

API

yoga.image.optimize(input_file, output_file, options={}, verbose=False, quiet=False)

Optimize given image.

Parameters:

input_file (str,file-like) – The path of the input image.
output_file (str,file-like) – The path of the output image.
options (dict) – Optimization options (see above).
verbose (bool) – ignored parameter.
quiet (bool) – ignored parameter.