Skip to main content

A library for converting to and from Aperture Science apf files, the custom extended apf2s, otb/wbmp images, and facedev's bruh format.

basic usage:

import apftool

apfString = apftool.apf.encode(pngObject) # turns image bytes object into apf string
pngObject = apftool.apf.decode(apfString) # turns apf string object into image bytes

additional tooling and software using apftool can be found at https://github.com/kbity/apftool, including custom MIME extensions.

format info:

APF is a custom format made by valve for the Portal 2 ARG. Documentation can be found here.

APF2 is a custom format, and superset of the original Portal 2 ARG Format. Documentation for APF2 can be found here.

MQIF is an experimental format from the KQI Hub, designed to demonstrate the usability of the scQOI compression algorithm. Limited info can be found here.

wbmp (Wireless bitmap) and otb (over-the-air bitmap) are simple image formats meant for transfering images before the modern internet was available to cell phones. wbmp came from the WAP forum, and otb came from Nokia. Info can be found here and here respectively.

bruh is an intentionally terrible format made by facedev. info can be found here... i guess?

funcs and features

encoders:

apf.encode(img: bytes | Image.Image, lineskip: int = 1, findbestlineskip: bool = False, returnbytes: bool = False) takes image bytes or pil image object and outputs apf string. lineskip is interleave value, findbestlineskip brute-forces different interleave values to the possible max of 199 and uses the smallest one. returnbytes makes it return bytes instead of a string.

apf2.encode(img: bytes | Image.Image, lineskip: int = None, findbestlineskip: bool = False, legacy: bool = False, trans = False, pal: int = 95, desc: str = "", prepalette: str = None, dodithering: bool = False, returnbytes: bool = False, compress: bool = True, topside_first: bool = False, emit_redundant_flag: bool = False, mode: int = None, combine: bool = False, avoid_run_breaks: bool = False, width: int = None, height: int = None, maxrunerror: float = 0, maxmotionerror: float = 0, verbose: bool = False, useadvancedquant: bool = True, dither_mode: str = "fs", compressor: str = None, wrapper: bool = True, compresslevel: int = 9)

takes image bytes or pil image object and outputs apf2 as a string or ascii bytes. lineskip is interleave value, findbestlineskip brute-forces different interleave values to the provided lineskip and uses the smallest one. legacy uses apf1-style 2 color data instead of a 95 color palette. trans sets transparency mode, with mode 0 being off, mode 1 being index 0 transparency (GIF-like, it overrides a color), and mode 2 being indexed alpha. pal allows you to manually force a smaller or larger palette anything over 95 will use APF2-1994's Dual Indexed Mode. Prepalette is an already encoded APF2 palette you input into the encoder to make the colors deterministic. dodithering enables or disables dithering. returnbytes makes it return bytes instead of a string. These options use the APF2-2000 mode: compress - disable RLE compression, allows for smaller file sizes where RLE is not beneficial. Topside_first makes the image scan top-to-bottom, like most formats. emit_redundant_flag - adds the implicit i flag explicitally to baseline 95 color images. mode - selects apf2 coding mode [0: 2 colors, 1: 95 colors, 2: 9025 colors, 3: near-truecolor, 4: near-truecolor with alpha, 5: truecolor, 6: truecolor with alpha, 7: quantized grayscale (based on 95 color mode), 8: 8-bit grayscale (based on 9025 color mode)], combine attempts to do cross-frame delta coding. avoid_run_breaks reduces the amount of transparency pixels emitted by combine, typically harms efficiency. width and height force the output resolution of the image. if both are specified, the output is streched to the specified resolution. if only 1 is present, the other is determined based on aspect ratio. If unspecfied, no scaling happens. maxrunerror and maxmotionerror control how lossy the image is, verbose increases logging output, useadvancedquant allows you to enable/disable the new quantizer, dither_mode sets its ditherer, which can be "fs" (floyd-steinberg) or "ordered" (bayer), compressor sets the apf2 post-compression algorithm (supports gzip, bzip2, and asciipak (ascii packing)). wrapper toggles wether to append an identifyable magic string to a compressed apf2. compresslevel sets the compression level for bzip2 and gzip

wbmp.encode(img: Image) takes pil image object and outputs wbmp bytes

otb.encode(img: Image, width=255, height=255) takes pil image object and outputs otb bytes. max size is 255x255. the size input is max size, the output may be smaller

bruh.encode(img: Image) takes pil image object and outputs bruh bytes

mqif.encode(img: list | Image.Image, transcolor: tuple = None) not fully implemented

decoders:

decode(data, format: str = 'PNG', returnImageObject: bool = False) takes in string or bytes and outputs bytes image or PIL image using best-guess for the decoders

apf.decode(apf: str, format: str = 'PNG', returnImageObject: bool = False) takes apf string and outputs either image bytes in specified format or pil image object

apf2.decode(af2: str, format: str = 'PNG', returnImageObject: bool = False, provide_extra_data: bool = False, composite_layers: bool = True) Literally a dropin replacement for decodeapf. provide_extra_data outputs frame delay data if applicable, and composite_layers choses weather to return a single image if the non-animated image has layers or if it should return the layers

wbmp.decode(wbmp: bytes, format: str = 'PNG', returnImageObject: bool = False) takes wbmp bytes and outputs either image bytes in specified format or pil image object

otb.decode(otab: bytes, format: str = 'PNG', returnImageObject: bool = False) hi i have the same usage as decodewbmp but for .otb images

bruh.decode(bruh: bytes, format: str = 'PNG', returnImageObject: bool = False) bruh decoder, acts the same as the others.

mqif.decode(mqif: bytes, format: str = 'GIF', returnImageObject: bool = False, provide_extra_data: bool = False) mqif decoder, acts the same as the others but defaults to GIF to support animation. provide_extra_data outputs frame delay data if applicable.

misc:

apftool provides many extensions tuples:

extensions - apf/apf2 extensions

extensions_apf - apf extensions

extensions_apf2 - apf2 extensions

extensions_wbmp - wbmp extensions

extensions_otb - otb extensions

extensions_bruh - bruh extensions

extensions_mqif - mqif extensions

extensions_txt - txt extensions, useful for weeding out generic apf

extensions_all - all supported apftool extensions, useful for universal decoder

version - reports apftool version

dependancies

PIL (pillow) is required

numpy and scipy are needed for high-quality, high-speed APF2 encoding, if missing the code will use a very slow and low quality fallback.

changelog:

1.2.1 - add support for 3 of apf2's compressed modes [bzip2, gzip, ascii packing]

1.2.0 - increase apfcli verbosity, add lossy encoding options. Allow apfcli to take its own formats as inputs and outputs, also adds a much better quantization algorithm and removes the limitations on indexed animations.

1.1.3 - add version field, add width and height options to apf2 encoding

1.1.2 - fix apftool

1.1.1 - fix A2K's q and n modes (~ should map to 255 in those modes)

1.1.0 - add APF2-2000 support, and add bg.fg support. Also you can now run findbestlineskip on animations. APF2-2000 is a major upgrade over APF2-1994 that adds Truecolor modes, internal alpha composting for layered images, cross-frame compression, and a lot more.

1.0.0 - restructure ABI, add MQIF support. Legacy ABI will be emulated. Also improve bruh and apf encoding speed. Also make apf2 decoder force webp for animated images in dual-indexed mode.

0.5.16 - add apfcli to the main project, fix dithering, fix palette edge cases, and rename encodeaf2 and decodeaf2 to encodeapf2 and decodeapf2

0.5.15 - add option to toggle dithering to the apf2 encoder and decoder

0.5.14 - update apf/apf2 encoder and decoder to use union types

0.5.13 - make the fixed palette thing not use a stupid amount of memory by using sklearn

0.5.12 - fix encoder with bytes input comparing against literal "bytes" type

0.5.11 - fix encoder trying to decode a non-existant input palette

0.5.10 - add predefined palette input for encoding, and remove duplicated code in the decode data functions

0.5.9 - fix wbmp encoding

0.5.8 - improve encoding speed for apf2 and wbmp

0.5.7 - fix index 0 bug with transparency mode 2 in 9025 color mode

0.5.6 - damn it i left the file testing code in af2tool

0.5.5 - implement apf2-1994 encoding and decoding (broken release)

0.5.2 - add bruh heristic to decodeany

0.5.1 - attempt to fix bruh resolution parsing issue

0.5.0 - add bruh encoder and decoder

0.4.3 - actually improve otb quality

0.4.2 - did not improve otb quality

0.4.1 - improve readme.md, fix otb encoder skuing due to flushing

0.4.0 - add support for otb images, improve readme.md, and add decodeany to decode all suported formats automatically

0.3.3 - make the af2 decoder more lenient

0.3.2 - i forgot but i think it made the af2 decoder more lenient

0.3.1 - fix 0.3.0

0.3.0 - add support for wbmp images, broken release

0.2.x - add apf2 support, i dont remember all the changes of the 0.2.x line

0.10 - initial release

Metadata

Release files for apftool 1.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apftool 1.2.1
File Size Uploaded Provenance Actions
apftool-1.2.1.tar.gz 36.3 kB Without provenance Details for apftool-1.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for apftool 1.2.1
File Interpreter ABI Platform Actions
apftool-1.2.1-py3-none-any.whl Python 3 none any Details for apftool-1.2.1-py3-none-any.whl

Total release size: 73.4 kB

Release files / apftool-1.2.1.tar.gz

Download URL apftool-1.2.1.tar.gz
Size 36.3 kB
Tags Source
SHA-256 checksum
How to use checksums
91ebe639ca42de81c2ce516cead1d92ab7815ef836cfd50112779af9516821c8
BLAKE2b-256 checksum
How to use checksums
6bb72e71e3c26c426ee30849595fb1d7f496c5ce7239763725b4821cf216815a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / apftool-1.2.1-py3-none-any.whl

Download URL apftool-1.2.1-py3-none-any.whl
Size 37.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4928b67847a485596f6f01160930e4a3e7c83ae6703bddda2c89c4a4f66d499c
BLAKE2b-256 checksum
How to use checksums
8f700c92fa05c0de723605318185734ce53545880cfeaf9fd15f9eb11c061004
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for apftool 1.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page