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