pywuffs: Python bindings for Wuffs the Library

Python bindings for Wuffs the Library.

class pywuffs.ImageDecoderQuirks

Bases: pybind11_object

See https://github.com/google/wuffs/blob/main/doc/note/quirks.md.

Members:

IGNORE_CHECKSUM : Favor faster decodes over rejecting invalid checksums.

GIF_DELAY_NUM_DECODED_FRAMES

GIF_FIRST_FRAME_LOCAL_PALETTE_MEANS_BLACK_BACKGROUND

GIF_QUIRK_HONOR_BACKGROUND_COLOR

GIF_IGNORE_TOO_MUCH_PIXEL_DATA

GIF_IMAGE_BOUNDS_ARE_STRICT

GIF_REJECT_EMPTY_FRAME

GIF_REJECT_EMPTY_PALETTE

GIF_DELAY_NUM_DECODED_FRAMES = <ImageDecoderQuirks.GIF_DELAY_NUM_DECODED_FRAMES: 1041635328>
GIF_FIRST_FRAME_LOCAL_PALETTE_MEANS_BLACK_BACKGROUND = <ImageDecoderQuirks.GIF_FIRST_FRAME_LOCAL_PALETTE_MEANS_BLACK_BACKGROUND: 1041635329>
GIF_IGNORE_TOO_MUCH_PIXEL_DATA = <ImageDecoderQuirks.GIF_IGNORE_TOO_MUCH_PIXEL_DATA: 1041635331>
GIF_IMAGE_BOUNDS_ARE_STRICT = <ImageDecoderQuirks.GIF_IMAGE_BOUNDS_ARE_STRICT: 1041635332>
GIF_QUIRK_HONOR_BACKGROUND_COLOR = <ImageDecoderQuirks.GIF_QUIRK_HONOR_BACKGROUND_COLOR: 1041635330>
GIF_REJECT_EMPTY_FRAME = <ImageDecoderQuirks.GIF_REJECT_EMPTY_FRAME: 1041635333>
GIF_REJECT_EMPTY_PALETTE = <ImageDecoderQuirks.GIF_REJECT_EMPTY_PALETTE: 1041635334>
IGNORE_CHECKSUM = <ImageDecoderQuirks.IGNORE_CHECKSUM: 1>
property name
property value
class pywuffs.ImageDecoderType

Bases: pybind11_object

Members:

BMP

GIF

NIE

PNG

TGA

WBMP

JPEG

BMP = <ImageDecoderType.BMP: 1112363040>
GIF = <ImageDecoderType.GIF: 1195984416>
JPEG = <ImageDecoderType.JPEG: 1246774599>
NIE = <ImageDecoderType.NIE: 1313424672>
PNG = <ImageDecoderType.PNG: 1347307296>
TGA = <ImageDecoderType.TGA: 1413955872>
WBMP = <ImageDecoderType.WBMP: 1463962960>
property name
property value
class pywuffs.JsonDecoderQuirks

Bases: pybind11_object

See https://github.com/google/wuffs/blob/main/std/json/decode_quirks.wuffs.

Members:

ALLOW_ASCII_CONTROL_CODES

ALLOW_BACKSLASH_A

ALLOW_BACKSLASH_CAPITAL_U

ALLOW_BACKSLASH_E

ALLOW_BACKSLASH_NEW_LINE

ALLOW_BACKSLASH_QUESTION_MARK

ALLOW_BACKSLASH_SINGLE_QUOTE

ALLOW_BACKSLASH_V

ALLOW_BACKSLASH_X_AS_CODE_POINTS

ALLOW_BACKSLASH_ZERO

ALLOW_COMMENT_BLOCK

ALLOW_COMMENT_LINE

ALLOW_EXTRA_COMMA

ALLOW_INF_NAN_NUMBERS

ALLOW_LEADING_ASCII_RECORD_SEPARATOR

ALLOW_LEADING_UNICODE_BYTE_ORDER_MARK

ALLOW_TRAILING_FILLER

EXPECT_TRAILING_NEW_LINE_OR_EOF

JSON_POINTER_ALLOW_TILDE_N_TILDE_R_TILDE_T

REPLACE_INVALID_UNICODE

ALLOW_ASCII_CONTROL_CODES = <JsonDecoderQuirks.ALLOW_ASCII_CONTROL_CODES: 1225364480>
ALLOW_BACKSLASH_A = <JsonDecoderQuirks.ALLOW_BACKSLASH_A: 1225364481>
ALLOW_BACKSLASH_CAPITAL_U = <JsonDecoderQuirks.ALLOW_BACKSLASH_CAPITAL_U: 1225364482>
ALLOW_BACKSLASH_E = <JsonDecoderQuirks.ALLOW_BACKSLASH_E: 1225364483>
ALLOW_BACKSLASH_NEW_LINE = <JsonDecoderQuirks.ALLOW_BACKSLASH_NEW_LINE: 1225364484>
ALLOW_BACKSLASH_QUESTION_MARK = <JsonDecoderQuirks.ALLOW_BACKSLASH_QUESTION_MARK: 1225364485>
ALLOW_BACKSLASH_SINGLE_QUOTE = <JsonDecoderQuirks.ALLOW_BACKSLASH_SINGLE_QUOTE: 1225364486>
ALLOW_BACKSLASH_V = <JsonDecoderQuirks.ALLOW_BACKSLASH_V: 1225364487>
ALLOW_BACKSLASH_X_AS_CODE_POINTS = <JsonDecoderQuirks.ALLOW_BACKSLASH_X_AS_CODE_POINTS: 1225364489>
ALLOW_BACKSLASH_ZERO = <JsonDecoderQuirks.ALLOW_BACKSLASH_ZERO: 1225364490>
ALLOW_COMMENT_BLOCK = <JsonDecoderQuirks.ALLOW_COMMENT_BLOCK: 1225364491>
ALLOW_COMMENT_LINE = <JsonDecoderQuirks.ALLOW_COMMENT_LINE: 1225364492>
ALLOW_EXTRA_COMMA = <JsonDecoderQuirks.ALLOW_EXTRA_COMMA: 1225364493>
ALLOW_INF_NAN_NUMBERS = <JsonDecoderQuirks.ALLOW_INF_NAN_NUMBERS: 1225364494>
ALLOW_LEADING_ASCII_RECORD_SEPARATOR = <JsonDecoderQuirks.ALLOW_LEADING_ASCII_RECORD_SEPARATOR: 1225364495>
ALLOW_LEADING_UNICODE_BYTE_ORDER_MARK = <JsonDecoderQuirks.ALLOW_LEADING_UNICODE_BYTE_ORDER_MARK: 1225364496>
ALLOW_TRAILING_FILLER = <JsonDecoderQuirks.ALLOW_TRAILING_FILLER: 1225364497>
EXPECT_TRAILING_NEW_LINE_OR_EOF = <JsonDecoderQuirks.EXPECT_TRAILING_NEW_LINE_OR_EOF: 1225364498>
JSON_POINTER_ALLOW_TILDE_N_TILDE_R_TILDE_T = <JsonDecoderQuirks.JSON_POINTER_ALLOW_TILDE_N_TILDE_R_TILDE_T: 1225364499>
REPLACE_INVALID_UNICODE = <JsonDecoderQuirks.REPLACE_INVALID_UNICODE: 1225364500>
property name
property value
class pywuffs.PixelBlend

Bases: pybind11_object

Encodes how to blend source and destination pixels, accounting for transparency. It encompasses the Porter-Duff compositing operators as well as the other blending modes defined by PDF.

Members:

SRC

SRC_OVER

SRC = <PixelBlend.SRC: 0>
SRC_OVER = <PixelBlend.SRC_OVER: 1>
property name
property value
class pywuffs.PixelFormat

Bases: pybind11_object

Common 8-bit-depth pixel formats. This list is not exhaustive; not all valid wuffs_base__pixel_format values are present.

Members:

A

Y

Y_16LE

Y_16BE

YA_NONPREMUL

YA_PREMUL

YCBCR

YCBCRA_NONPREMUL

YCBCRK

YCOCG

YCOCGA_NONPREMUL

YCOCGK

INDEXED__BGRA_NONPREMUL

INDEXED__BGRA_PREMUL

INDEXED__BGRA_BINARY

BGR_565

BGR

BGRA_NONPREMUL

BGRA_NONPREMUL_4X16LE

BGRA_PREMUL

BGRA_PREMUL_4X16LE

BGRA_BINARY

BGRX

RGB

RGBA_NONPREMUL

RGBA_NONPREMUL_4X16LE

RGBA_PREMUL

RGBA_PREMUL_4X16LE

RGBA_BINARY

RGBX

CMY

CMYK

A = <PixelFormat.A: 33554440>
BGR = <PixelFormat.BGR: 2147485832>
BGRA_BINARY = <PixelFormat.BGRA_BINARY: 2197850248>
BGRA_NONPREMUL = <PixelFormat.BGRA_NONPREMUL: 2164295816>
BGRA_NONPREMUL_4X16LE = <PixelFormat.BGRA_NONPREMUL_4X16LE: 2164308923>
BGRA_PREMUL = <PixelFormat.BGRA_PREMUL: 2181073032>
BGRA_PREMUL_4X16LE = <PixelFormat.BGRA_PREMUL_4X16LE: 2181086139>
BGRX = <PixelFormat.BGRX: 2415954056>
BGR_565 = <PixelFormat.BGR_565: 2147485029>
CMY = <PixelFormat.CMY: 3221358728>
CMYK = <PixelFormat.CMYK: 3489892488>
INDEXED__BGRA_BINARY = <PixelFormat.INDEXED__BGRA_BINARY: 2198077448>
INDEXED__BGRA_NONPREMUL = <PixelFormat.INDEXED__BGRA_NONPREMUL: 2164523016>
INDEXED__BGRA_PREMUL = <PixelFormat.INDEXED__BGRA_PREMUL: 2181300232>
RGB = <PixelFormat.RGB: 2684356744>
RGBA_BINARY = <PixelFormat.RGBA_BINARY: 2734721160>
RGBA_NONPREMUL = <PixelFormat.RGBA_NONPREMUL: 2701166728>
RGBA_NONPREMUL_4X16LE = <PixelFormat.RGBA_NONPREMUL_4X16LE: 2701179835>
RGBA_PREMUL = <PixelFormat.RGBA_PREMUL: 2717943944>
RGBA_PREMUL_4X16LE = <PixelFormat.RGBA_PREMUL_4X16LE: 2717957051>
RGBX = <PixelFormat.RGBX: 2952824968>
Y = <PixelFormat.Y: 536870920>
YA_NONPREMUL = <PixelFormat.YA_NONPREMUL: 553648136>
YA_PREMUL = <PixelFormat.YA_PREMUL: 570425352>
YCBCR = <PixelFormat.YCBCR: 1073875080>
YCBCRA_NONPREMUL = <PixelFormat.YCBCRA_NONPREMUL: 1090750600>
YCBCRK = <PixelFormat.YCBCRK: 1342408840>
YCOCG = <PixelFormat.YCOCG: 1610745992>
YCOCGA_NONPREMUL = <PixelFormat.YCOCGA_NONPREMUL: 1627621512>
YCOCGK = <PixelFormat.YCOCGK: 1879279752>
Y_16BE = <PixelFormat.Y_16BE: 537919499>
Y_16LE = <PixelFormat.Y_16LE: 536870923>
property name
property value
class pywuffs.PixelSubsampling

Bases: pybind11_object

wuffs_base__pixel_subsampling encodes whether sample values cover one pixel or cover multiple pixels. See https://github.com/google/wuffs/blob/main/doc/note/pixel-subsampling.md

Members:

NONE

K444

K440

K422

K420

K411

K410

K410 = <PixelSubsampling.K410: 3223808>
K411 = <PixelSubsampling.K411: 3158016>
K420 = <PixelSubsampling.K420: 1118464>
K422 = <PixelSubsampling.K422: 1052672>
K440 = <PixelSubsampling.K440: 65792>
K444 = <PixelSubsampling.NONE: 0>
NONE = <PixelSubsampling.NONE: 0>
property name
property value
class pywuffs.wuffs_base__more_information

Bases: pybind11_object

Holds additional fields. The flavor field follows the base38 namespace convention (https://github.com/google/wuffs/blob/main/doc/note/base38-and-fourcc.md). The other fields’ semantics depends on the flavor.

property flavor
io_redirect__fourcc(self: pywuffs.wuffs_base__more_information) → int
io_seek__position(self: pywuffs.wuffs_base__more_information) → int
metadata__fourcc(self: pywuffs.wuffs_base__more_information) → int
metadata_parsed__chrm(self: pywuffs.wuffs_base__more_information, arg0: int) → int
metadata_parsed__gama(self: pywuffs.wuffs_base__more_information) → int
metadata_parsed__srgb(self: pywuffs.wuffs_base__more_information) → int
property w
property x
property y
property z
class pywuffs.wuffs_base__pixel_config

Bases: pybind11_object

Holds information about decoded pixel buffer.

height(self: pywuffs.wuffs_base__pixel_config) → int
is_valid(self: pywuffs.wuffs_base__pixel_config) → bool
pixbuf_len(self: pywuffs.wuffs_base__pixel_config) → int
pixel_format(self: pywuffs.wuffs_base__pixel_config) → wuffs_aux_wrap::PixelFormat
pixel_subsampling(self: pywuffs.wuffs_base__pixel_config) → wuffs_aux_wrap::PixelSubsampling
width(self: pywuffs.wuffs_base__pixel_config) → int

Simplified “auxiliary” API.

class pywuffs.aux.ImageDecoder

Bases: pybind11_object

Image decoder class.

decode(*args, **kwargs)

Overloaded function.

  1. decode(self: pywuffs.aux.ImageDecoder, arg0: bytes) -> pywuffs.aux.ImageDecodingResult

Decodes image using given byte buffer.

Parameters:

data (bytes) – a byte buffer holding encoded image.

Returns:

image decoding result.

Return type:

ImageDecodingResult

  1. decode(self: pywuffs.aux.ImageDecoder, arg0: str) -> pywuffs.aux.ImageDecodingResult

Decodes image using given file path.

Parameters:

path_to_file (str) – path to an image file.

Returns:

image decoding result.

Return type:

ImageDecodingResult

class pywuffs.aux.ImageDecoderConfig

Bases: pybind11_object

Image decoder configuration.

property background_color

The background_color is used to fill the pixel buffer after callbacks.AllocPixbuf returns, if it is valid in the wuffs_base__color_u32_argb_premul__is_valid sense. The default value, 0x0000_0001, is not valid since its Blue channel value (0x01) is greater than its Alpha channel value (0x00). A valid background_color will typically be overwritten when pixel_blend is PixelBlend.SRC, but might still be visible on partial (not total) success or when pixel_blend is PixelBlend.SRC_OVER and the decoded image is not fully opaque.

Type:

int

property enabled_decoders

list of ImageDecoderType.

Type:

list

property flags

list of ImageDecoderFlags, empty by default.

Type:

list

property max_incl_dimension

Decoding fails (with ImageDecoderErrors.MaxInclDimensionExceeded) if the image’s width or height is greater than max_incl_dimension.

Type:

int

property max_incl_metadata_length

Decoding fails (with ImageDecoderErrors.MaxInclDimensionExceeded) if any opted-in (via flags bits) metadata is longer than max_incl_metadata_length.

Type:

int

property pixel_blend

pixel blend mode, default is PixelBlend.SRC.

Type:

PixelBlend

property pixel_format

  • PixelFormat.BGR_565

  • PixelFormat.BGR

  • PixelFormat.BGRA_NONPREMUL

  • PixelFormat.BGRA_NONPREMUL_4X16LE

  • PixelFormat.BGRA_PREMUL

  • PixelFormat.RGBA_NONPREMUL

  • PixelFormat.RGBA_PREMUL

Type:

PixelFormat

Type:

Destination pixel format, default is PixelFormat.BGRA_PREMUL which is 4 bytes per pixel (8 bits per channel × 4 channels). Currently supported formats are

property quirks

list of ImageDecoderQuirks, empty by default (PNG decoder will always have ImageDecoderQuirks.IGNORE_CHECKSUM quirk enabled implicitly).

Type:

list

class pywuffs.aux.ImageDecoderError

Bases: pybind11_object

FailedToOpenFile = 'wuffs_aux_wrap::ImageDecoder::Decode: failed to open file'
MaxInclDimensionExceeded = 'wuffs_aux::DecodeImage: max_incl_dimension exceeded'
MaxInclMetadataLengthExceeded = 'wuffs_aux::DecodeImage: max_incl_metadata_length exceeded'
OutOfMemory = 'wuffs_aux::DecodeImage: out of memory'
UnexpectedEndOfFile = 'wuffs_aux::DecodeImage: unexpected end of file'
UnsupportedImageFormat = 'wuffs_aux::DecodeImage: unsupported image format'
UnsupportedMetadata = 'wuffs_aux::DecodeImage: unsupported metadata'
UnsupportedPixelBlend = 'wuffs_aux::DecodeImage: unsupported pixel blend'
UnsupportedPixelConfiguration = 'wuffs_aux::DecodeImage: unsupported pixel configuration'
UnsupportedPixelFormat = 'wuffs_aux::DecodeImage: unsupported pixel format'
class pywuffs.aux.ImageDecoderFlags

Bases: pybind11_object

Flags to defining image decoder behavior (e.g. metadata reporting).

Members:

REPORT_METADATA_BGCL : Background Color.

REPORT_METADATA_CHRM : Primary Chromaticities and White Point.

REPORT_METADATA_EXIF : Exchangeable Image File Format.

REPORT_METADATA_GAMA : Gamma Correction.

REPORT_METADATA_ICCP : International Color Consortium Profile.

REPORT_METADATA_KVP : Key-Value Pair. For PNG files, this includes iTXt, tEXt and zTXt chunks. In the HandleMetadata callback, the raw argument contains UTF-8 strings.

REPORT_METADATA_MTIM : Modification Time.

REPORT_METADATA_OFS2 : Offset (2-Dimensional).

REPORT_METADATA_PHYD : Physical Dimensions.

REPORT_METADATA_SRGB : Standard Red Green Blue (Rendering Intent).

REPORT_METADATA_XMP : Extensible Metadata Platform.

REPORT_METADATA_BGCL = <ImageDecoderFlags.REPORT_METADATA_BGCL: 1>
REPORT_METADATA_CHRM = <ImageDecoderFlags.REPORT_METADATA_CHRM: 2>
REPORT_METADATA_EXIF = <ImageDecoderFlags.REPORT_METADATA_EXIF: 4>
REPORT_METADATA_GAMA = <ImageDecoderFlags.REPORT_METADATA_GAMA: 8>
REPORT_METADATA_ICCP = <ImageDecoderFlags.REPORT_METADATA_ICCP: 16>
REPORT_METADATA_KVP = <ImageDecoderFlags.REPORT_METADATA_KVP: 32>
REPORT_METADATA_MTIM = <ImageDecoderFlags.REPORT_METADATA_MTIM: 64>
REPORT_METADATA_OFS2 = <ImageDecoderFlags.REPORT_METADATA_OFS2: 128>
REPORT_METADATA_PHYD = <ImageDecoderFlags.REPORT_METADATA_PHYD: 256>
REPORT_METADATA_SRGB = <ImageDecoderFlags.REPORT_METADATA_SRGB: 512>
REPORT_METADATA_XMP = <ImageDecoderFlags.REPORT_METADATA_XMP: 1024>
property name
property value
class pywuffs.aux.ImageDecodingResult

Bases: pybind11_object

Image decoding result. The fields depend on whether decoding succeeded: - On total success, the error_message is empty and pixbuf is not empty. - On partial success (e.g. the input file was truncated but we are still able to decode some of the pixels), error_message is non-empty but pixbuf is not empty. It is up to the caller whether to accept or reject partial success. - On failure, the error_message is non-empty and pixbuf is empty.

property error_message

error message, empty on success, one of ImageDecoderError on error.

Type:

str

property pixbuf

decoded pixel buffer (uint8 Numpy array of [H, W, C] shape).

Type:

np.array

property pixcfg

decoded pixel buffer config.

Type:

wuffs_base__pixel_config

property reported_metadata

a list object containing reported data (only filled if any metadata was decoded and the corresponding ImageDecoderFlag flag was set).

Type:

list

class pywuffs.aux.JsonDecoder

Bases: pybind11_object

JSON decoder class.

decode(*args, **kwargs)

Overloaded function.

  1. decode(self: pywuffs.aux.JsonDecoder, arg0: bytes) -> pywuffs.aux.JsonDecodingResult

Decodes JSON using given byte buffer.

Parameters:

data (bytes) – a byte buffer holding JSON string.

Returns:

JSON decoding result.

Return type:

JsonDecodingResult

  1. decode(self: pywuffs.aux.JsonDecoder, arg0: str) -> pywuffs.aux.JsonDecodingResult

Decodes JSON using given file path.

Parameters:

path_to_file (str) – path to a JSON file.

Returns:

JSON decoding result.

Return type:

JsonDecodingResult

class pywuffs.aux.JsonDecoderConfig

Bases: pybind11_object

JSON decoder configuration.

property json_pointer

JSON pointer.

Type:

str

property quirks

list of JsonDecoderQuirks, empty by default.

Type:

list

class pywuffs.aux.JsonDecoderError

Bases: pybind11_object

BadBackslashEscape = 'json: bad backslash-escape'
BadC0ControlCode = 'json: bad C0 control code'
BadDepth = 'wuffs_aux_wrap::JsonDecoder::Decode: bad depth'
BadInput = 'json: bad input'
BadJsonPointer = 'wuffs_aux::DecodeJson: bad JSON Pointer'
BadNewLineInAString = 'json: bad new-line in a string'
BadQuirkCombination = 'json: bad quirk combination'
BadUtf8 = 'json: bad UTF-8'
DuplicateMapKey = 'wuffs_aux_wrap::JsonDecoder::Decode: duplicate map key: key='
FailedToOpenFile = 'wuffs_aux_wrap::JsonDecoder::Decode: failed to open file'
NoMatch = 'wuffs_aux::DecodeJson: no match'
NonContainerStackEntry = 'wuffs_aux_wrap::JsonDecoder::Decode: non-container stack entry'
NonStringMapKey = 'wuffs_aux_wrap::JsonDecoder::Decode: non-string map key'
UnsupportedNumberLength = 'json: unsupported number length'
UnsupportedRecursionDepth = 'json: unsupported recursion depth'
class pywuffs.aux.JsonDecodingResult

Bases: pybind11_object

JSON decoding result. The fields depend on whether decoding succeeded: - On total success, the error_message is empty and parsed is not empty. - On failure, the error_message is non-empty and parsed is empty.

property cursor_position

cursor position.

Type:

int

property error_message

error message, empty on success, one of JsonDecoderError on error.

Type:

str

property parsed

parsed JSON data.

Type:

obj

class pywuffs.aux.MetadataEntry

Bases: pybind11_object

Holds parsed metadata piece.

property data

Parsed metadata (1D uint8 Numpy array).

Type:

np.array

property minfo

Info on parsed metadata.

Type:

wuffs_base__more_information