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,
})

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.