GitLocker: The Coding Marketplace

Description:

pyoxipng 9.0.0

pyoxipng

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

API

optimize
optimize_from_memory
RawImage

Options

filter
interlace
strip
deflate

Development

License

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:

**kwargs – Options

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
set[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 milliseconds) on optimizations. Further potential optimizations are skipped if the timeout is exceeded
int | None
None

filter
Initialize the filter set 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(set[bytes])
Strip specific chunks

oxipng.StripChunks.safe()
Strip chunks that won't affect rendering (all but cICP, iCCP, sRGB, pHYs, acTL, fcTL, fdAT)

oxipng.StripChunks.keep(set[bytes])
Strip all non-critical chunks except these

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

Install Rust
Install Python 3.8+
Install Pipenv
Clone this repository and navigate to it via command line
git clone https://github.com/nfrasser/pyoxipng.git
cd pyoxipng

Install dependencies
pipenv install --dev

Activate the dev environment
pipenv shell

Build
maturin develop

Run tests
pytest

Format code
black .

License
MIT