Skip to content

Latest commit

 

History

History
310 lines (219 loc) · 12.9 KB

README.md

File metadata and controls

310 lines (219 loc) · 12.9 KB

pyoxipng

CI PyPI

Python wrapper for multithreaded .png image file optimizer oxipng (written in Rust). Use pyoxipng to reduce the file size of your PNG images.

Jump to a section

Installation

Install from PyPI:

pip install pyoxipng

Import in your Python code:

import oxipng

API

oxipng.optimize(input, output=None, **kwargs)

Optimize a file on disk.

Parameters:

  • input (str | bytes | PathLike) – path to input file to optimize
  • output (str | bytes | PathLike, optional) – path to optimized output result file. If not specified, overwrites input. Defaults to None
  • **kwargs – Options

Returns

  • None

Raises

  • oxipng.PngError – optimization could not be completed

Examples:

Optimize a file on disk and overwrite

oxipng.optimize("/path/to/image.png")

Optimize a file and save to a new location:

oxipng.optimize("/path/to/image.png", "/path/to/image-optimized.png")

oxipng.optimize_from_memory(data, **kwargs)

Optimize raw data from a PNG file loaded in Python as a bytes object:

Parameters:

  • data (bytes) – raw PNG data to optimize
  • **kwargs – Options

Returns

  • (bytes) – optimized raw PNG data

Raises

  • oxipng.PngError – optimization could not be completed

Examples:

data = ...  # bytes of png data
optimized_data = oxipng.optimize_from_memory(data)
with open("/path/to/image-optimized.png", "wb") as f:
    f.write(optimized_data)

oxipng.RawImage

Create an optimized PNG file from raw image data:

raw = oxipng.RawImage(data, width, height)
optimized_data = raw.create_optimized_png()

By default, assumes the input data is 8-bit, row-major RGBA, where every 4 bytes represents one pixel with Red-Green-Blue-Alpha channels. To interpret non-RGBA data, specify a color_type parameter with the oxipng.ColorType class:

Method Description
oxipng.ColorType.grayscale(int | None) Grayscale, with one color channel. Specify optional shade of gray that should be rendered as transparent.
oxipng.ColorType.rgb(tuple[int, int, int]) RGB, with three color channels. Specify optional color value that should be rendered as transparent.
oxipng.ColorType.indexed(list[[tuple[int, int, int, int]]) Indexed, with one byte per pixel representing a color from the palette. Specify palette containing the colors used, up to 256 entries.
oxipng.ColorType.grayscale_alpha() Grayscale + Alpha, with two color channels.
oxipng.ColorType.rgba() RGBA, with four color channels.

Parameters:

  • data (bytes | bytearray) – Raw image data bytes. Format depends on color_type and bit_depth parameters
  • width (int) – Width of raw image, in pixels
  • height (int) – Height of raw image, in pixels
  • color_type ([oxipng.ColorType, optional) – Descriptor for color type used to represent this image. Optional, defaults to oxipng.ColorType.rgba()
  • bit_depth (int, optional) – Bit depth of raw image. Optional, defaults to 8

Examples:

Save RGB image data from a JPEG file, interpreting black pixels as transparent.

from PIL import Image
import numpy as np

# Load an image file with Pillow
jpg = Image.open("/path/to/image.jpg")

# Convert to RGB numpy array
rgb_array = np.array(jpg.convert("RGB"), dtype=np.uint8)
height, width, channels = rgb_array.shape

# Create raw image with sRGB color profile
data = rgb_array.tobytes()
color_type = oxipng.ColorType.rgb((0, 0, 0))  # black is transparent
raw = oxipng.RawImage(data, width, height, color_type=color_type)
raw.add_png_chunk(b"sRGB", b"\0")

# Optimize and save
optimized = raw.create_optimized_png(level=6)
with open("/path/to/image/optimized.png", "wb") as f:
    f.write(optimized)

Save with data where bytes reference a color palette

data = b"\0\1\2..."  # get index data
palette = [[0, 0, 0, 255], [1, 23, 234, 255], ...]
color_type = oxipng.ColorType.indexed(palette)
raw = oxipng.RawImage(data, 100, 100, color_type=color_type)
optimized = raw.create_optimized_png()

Methods:

add_png_chunk(name, data)

Add a png chunk, such as b"iTXt", to be included in the output

Parameters:

  • name (bytes) – PNG chunk identifier
  • data (bytes | bytarray)

Returns:

  • None

add_icc_profile(data)

Add an ICC profile for the image

Parameters:

  • data (bytes) – ICC profile data

Returns:

  • None

create_optimized_png(**kwargs)

Create an optimized png from the raw image data using the options provided

Parameters:

Returns:

  • (bytes) optimized PNG image data

Options

optimize , optimize_from_memory and RawImage.create_optimized_png accept the following options as keyword arguments.

Example:

oxipng.optimize("/path/to/image.png", level=6, fix_errors=True, interlace=oxipng.Interlacing.Adam7)
Option Description Type Default
level Set the optimization level to an integer between 0 and 6 (inclusive) int 2
fix_errors Attempt to fix errors when decoding the input file rather than throwing PngError bool False
force Write to output even if there was no improvement in compression bool False
filter Which filters to try on the file. Use Use enum values from oxipng.RowFilter Sequence[RowFilter] [RowFilter.NoOp]
interlace Whether to change the interlacing type of the file. None will not change current interlacing type Interlacing | None None
optimize_alpha Whether to allow transparent pixels to be altered to improve compression bool False
bit_depth_reduction Whether to attempt bit depth reduction bool True
color_type_reduction Whether to attempt color type reduction bool True
palette_reduction Whether to attempt palette reduction bool True
grayscale_reduction Whether to attempt grayscale reduction bool True
idat_recoding If any type of reduction is performed, IDAT recoding will be performed regardless of this setting bool True
scale_16 Whether to forcibly reduce 16-bit to 8-bit by scaling bool False
strip Which headers to strip from the PNG file, if any. Specify with oxipng.StripChunks StripChunks StripChunks.none()
deflate Which DEFLATE algorithm to use. Specify with oxipng.Deflaters Deflaters Deflaters.libdeflater()
fast_evaluation Whether to use fast evaluation to pick the best filter bool False
timeout Maximum amount of time to spend (in seconds) on optimizations. Further potential optimizations skipped if the timeout is exceeded float | None None

filter

Initialize a filter list or tuple with any of the following oxipng.RowFilter enum options:

  • oxipng.RowFilter.NoOp
  • oxipng.RowFilter.Sub
  • oxipng.RowFilter.Up
  • oxipng.RowFilter.Average
  • oxipng.RowFilter.Paeth
  • oxipng.RowFilter.Bigrams
  • oxipng.RowFilter.BigEnt
  • oxipng.RowFilter.Brute

interlace

Set interlace to None to keep existing interlacing or to one of following oxipng.Interlacing enum options:

  • oxipng.Interlacing.Off (interlace disabled)
  • oxipng.Interlacing.Adam7 (interlace enabled)

strip

Initialize the strip option with one of the following static methods in the oxipng.StripChunks class.

Method Description
oxipng.StripChunks.none() None
oxipng.StripChunks.strip(Sequence[bytes]) Strip chunks specified in the given list
oxipng.StripChunks.safe() Strip chunks that won't affect rendering (all but cICP, iCCP, sRGB, pHYs, acTL, fcTL, fdAT)
oxipng.StripChunks.keep(Sequence[bytes]) Strip all non-critical chunks except those in the given list
oxipng.StripChunks.all() Strip all non-critical chunks

deflate

Initialize the deflate option with one of the following static methods in the oxipng.Deflaters class.

Method Description
oxipng.Deflaters.libdeflater(int) Libdeflater with compression level [0-12]
oxipng.Deflaters.zopfli(int) Zopfli with number of compression iterations to do [1-255]

Development

  1. Install Rust
  2. Install Python 3.8+
  3. Install Pipenv
  4. Clone this repository and navigate to it via command line 
    git clone https://github.com/nfrasser/pyoxipng.git
cd pyoxipng
  5. Install dependencies 
    pipenv install --dev
  6. Activate the dev environment 
    pipenv shell
  7. Build 
    maturin develop
  8. Run tests 
    pytest
  9. Format code 
    ruff check .
ruff format .

License

MIT