Image codec contracts

Optional module · pdftoolkit/pdf-codecs 0.1.0

English | Français

The public entry point is Decoder::decode(DecodeRequest): DecodedImage. PhpDecoder implements it by creating the requested codec with an immutable DecodeLimits policy. Parsers, entropy contexts, intermediate buffers and work counters belong to that invocation. Reusing a decoder after a failed request does not reuse the failed image's tables, globals or budget.

Encoded input

DecodeRequest carries the codec and encoded bytes. colorTransform applies only to JPEG and accepts 0, 1 or absence. globals applies only to JBIG2 and contains the already-resolved global stream bytes. Resolving PDF references, decryption, preceding filters and the PDF image dictionary belongs to Reader. The library does not infer a format from a filename or execute content supplied by an image.

use PDFToolkit\Codecs\Codec;
use PDFToolkit\Codecs\DecodeLimits;
use PDFToolkit\Codecs\DecodeRequest;
use PDFToolkit\Codecs\PhpDecoder;

$decoder = new PhpDecoder(new DecodeLimits(
    maxInputBytes: 8 * 1024 * 1024,
    maxOutputBytes: 32 * 1024 * 1024,
    maxPixels: 4_000_000,
));
$image = $decoder->decode(new DecodeRequest(Codec::Jpeg, $encodedBytes));
$firstSample = $image->components[0]->sample(0, 0);

The caller supplies $encodedBytes. This example neither opens a file nor downloads data. The executable example in examples/decode.php explicitly handles local files as an application outside the decoding library.

Decoded results

DecodedImage contains the reference-grid dimensions and origin, ordered ComponentPlane objects, ColorInformation and channel definitions. Each component records its own dimensions, sampling separation, origin, precision, signedness and alpha association. A component's dimensions can differ from those of another component. Consumers must inspect these fields before interleaving or displaying samples.

Plane bytes use row-padded, MSB-first samples. Signed values use two's complement at the declared precision. ComponentPlane::sample(x, y) exposes that value without reducing it to a byte. For example, a signed twelve-bit value of -1 is represented by twelve set bits, not by a PHP-specific serialized integer. Unused bits at the end of a row are not extra pixels.

Colour metadata and sample values are separate. Embedded ICC profiles are retained bytes, not instructions to access the filesystem. JPEG's defined colour transforms and JPEG 2000's codestream transforms are decoding operations; ICC conversion, display rendering, PDF Decode arrays and transparency compositing remain consumer operations. See the codec guides for their precise output interpretations.

Budgets and failure

DecodeBudget checks input, output, dimensions, work and accounted allocations before the corresponding operation. The immutable DecodeLimits also defines component, metadata, segment, tile and nesting limits. The applicable limits depend on the codec's structures. The input limit includes JBIG2 globals. Allocation accounting is cumulative over a request; it is deliberately distinct from the PHP process's current memory usage and does not replace a process memory limit.

The caller handles three different conditions:

There is no automatic retry with relaxed bounds or silent truncation. Metadata and fixtures document the implemented profiles. A passing fixture corpus is evidence for those cases, not a declaration that every possible bitstream has been exercised.

Relationship to PDFToolkit

This package has no dependency on the core or Reader. It does not discover native executables, invoke a process or install Composer packages. Reader owns the adapter that selects an available compatible native engine first, then this optional PHP decoder. The same library can also be used directly by an application that does not read PDF documents.

Guide source at the documented commit ↗