IF Commons GitHub

png

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-formats FR-012

Pictures with no outside package (commons 0001-formats FR-012): a PNG read into eight-bit RGBA and written back, a picture resized with Pillow's Lanczos filter in its fixed point (on premultiplied alpha for RGBA), laid over another as Pillow's alpha_composite lays it, fitted as Pillow's thumbnail fits it, gathered into a multi-size icon file of PNG frames and read back from one, and two files compared by their pixels rather than their bytes (two zlib encoders give different bytes for one picture). Also a #rrggbb colour read into its channels and its relative luminance as WCAG measures it.

The reader takes every PNG that is not interlaced: greyscale at 1, 2, 4, 8 and 16 bits, palette at 1, 2, 4 and 8 bits, and RGB, greyscale with alpha and RGBA at 8 and 16 bits, with tRNS transparency for greyscale, RGB and palette, and every filter (None, Sub, Up, Average, Paeth). Sixteen-bit samples keep their high byte. It refuses what is not a PNG it can trust, with a typed PngError: a bad signature, a chunk whose CRC-32 is wrong, data cut short, a colour type and bit depth PNG does not define, an interlaced (Adam7) picture, an unknown critical chunk, and a picture of more than MAX_PIXELS pixels, refused before anything is allocated or inflated for it; the inflater is stopped as soon as it gives more bytes than the picture needs, so a small hostile file cannot make it allocate more. Writers take a well-formed picture; a malformed one (a size that is not a positive integer, data of the wrong length) is a programming error and throws a RangeError.

Taken from erga's lib/ts/png. What changed: readers return a typed error rather than a sentence, check every chunk's CRC and the picture's size, read the sub-byte depths and the tRNS of greyscale and RGB that erga ignored, and refuse an out-of-range palette index; erga's resize (each channel alone) is resizeChannels and its resized (on premultiplied alpha) is resize; hexRgb returns undefined for what is not a colour rather than black, and luminance takes channels rather than a hex string; composite clips an overlay that starts left of or above its base, and premultiply leaves a picture without alpha as it is.

import { filled, readPng, writePng } from "./png.ts";
const png = await writePng(filled(2, 2, [255, 0, 0, 128]));
await readPng(png); // { kind: "ok", value: { width: 2, height: 2, channels: 4, data: Uint8Array [255, 0, 0, 128, ...] } }

Source: commons/formats/src/png.ts

22 of 48 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

pngnamespace
namespace png
png.Picturetypeno test imports it
type Picture = { readonly width: number; readonly height: number; readonly channels: 3 | 4; readonly data: Uint8Array };

A raster: its size, its channels (3 for RGB, 4 for RGBA) and its bytes, row by row, eight bits a channel.

png.Rgbtypeno test imports it
type Rgb = readonly [number, number, number];

A colour's red, green and blue, each 0 to 255.

png.Rgbatypeno test imports it
type Rgba = readonly [number, number, number, number];

A colour's red, green, blue and alpha, each 0 to 255.

png.MAX_PIXELSconstno test imports it
const MAX_PIXELS: number

The most pixels a picture read may have: 2^24 (16,777,216, a 4096 by 4096 square). Its RGBA is then at most 64 MiB, and the inflated data of the largest kind (16-bit RGBA) at most 128 MiB. A file that declares more is refused as too-large before anything is read.

png.PngErrortypeno test imports it
type PngError = | { readonly kind: "signature"; readonly format: "png" | "ico" } | { readonly kind: "crc"; readonly … (571 characters)
type PngError =
  | { readonly kind: "signature"; readonly format: "png" | "ico" }
  | { readonly kind: "crc"; readonly chunk: string; readonly at: number }
  | { readonly kind: "truncated"; readonly message: string }
  | { readonly kind: "malformed"; readonly message: string }
  | { readonly kind: "unsupported"; readonly message: string }
  | { readonly kind: "interlaced" }
  | { readonly kind: "too-large"; readonly width: number; readonly height: number; readonly limit: number }
  | { readonly kind: "ico-frame"; readonly index: number; readonly error: PngError };

Why bytes are not a PNG or icon file this reader takes.

png.formatPngErrorfunctionno test imports it
function formatPngError(e: PngError): string

A PNG error as one sentence.

png.filledfunctionno test imports it
function filled(width: number, height: number, rgba: Rgba): Picture

A picture of one colour, RGBA. A size that is not a positive integer throws a RangeError.

png.rgbOffunctionno test imports it
function rgbOf(p: Picture): Picture

The picture without its alpha; a picture without alpha as it is.

png.rgbaOffunctionno test imports it
function rgbaOf(p: Picture): Picture

The picture with alpha, opaque where it had none; a picture with alpha as it is.

png.readPngfunctionno test imports it
function readPng(bytes: Uint8Array<ArrayBufferLike>): Promise<Result<Picture, PngError>>

A PNG read into eight-bit RGBA, its filters undone and its palette and transparency applied; or why it cannot be.

png.writePngfunctionno test imports it
function writePng(p: Picture): Promise<Uint8Array<ArrayBufferLike>>

A picture written as an eight-bit RGB or RGBA PNG, each row unfiltered, its zlib stream the platform's CompressionStream.

png.premultiplyfunctionno test imports it
function premultiply(p: Picture): Picture

The picture with each colour channel multiplied by its alpha, rounded as Pillow rounds; a picture without alpha as it is.

png.unpremultiplyfunctionno test imports it
function unpremultiply(p: Picture): Picture

The picture with each colour channel divided by its alpha again, as Pillow divides; a picture without alpha as it is.

png.resizeChannelsfunctionno test imports it
function resizeChannels(p: Picture, width: number, height: number): Picture

A picture resized with Pillow's Lanczos filter in its fixed point, each channel filtered on its own (alpha too, and the colour channels without regard to it). A size that is not a positive integer throws a RangeError.

png.resizefunctionno test imports it
function resize(p: Picture, width: number, height: number): Picture

A picture resized as Pillow resizes it with its Lanczos filter: an RGBA picture on premultiplied alpha. The same size gives it back.

png.compositefunctionno test imports it
function composite(base: Picture, over: Picture, left: number, top: number): Picture

over laid on base with its top left corner at (left, top), as Pillow's alpha_composite lays it; what falls outside base is cut off. The result has alpha; a picture without alpha is taken as opaque.

png.flatOnfunctionno test imports it
function flatOn(colour: Rgb, width: number, height: number, art: Picture, left: number, top: number): Picture

art laid at (left, top) on an opaque canvas of colour, the result without alpha.

png.thumbnailSizefunctionno test imports it
function thumbnailSize(p: Picture, width: number, height: number): readonly [number, number] | undefined

The size Pillow's thumbnail gives a picture fitted in width by height, its aspect kept; undefined where it already fits.

png.writeIcofunctionno test imports it
function writeIco(p: Picture, sizes: readonly number[]): Promise<Uint8Array<ArrayBufferLike>>

A multi-size icon file of PNG frames, as Pillow writes one: one frame for each size asked that is at most the picture's width, height and 256, smallest first, each the picture fitted in that square (thumbnailSize) and resized (resize).

png.readIcofunctionno test imports it
function readIco(bytes: Uint8Array<ArrayBufferLike>): Promise<Result<readonly Picture[], PngError>>

Every frame of an icon file whose frames are PNGs, in the order of its directory; or why it cannot be read.

png.samePixelsfunctionno test imports it
function samePixels(a: Picture, b: Picture): boolean

Whether two pictures have the same size and the same RGBA pixels (a picture without alpha taken as opaque).

png.samePicturefunctionno test imports it
function samePicture(a: Uint8Array<ArrayBufferLike>, b: Uint8Array<ArrayBufferLike>): Promise<boolean>

Whether two PNG files, or two icon files, hold the same pictures pixel for pixel, whatever their zlib streams; false where either cannot be read.

png.hexRgbfunctionno test imports it
function hexRgb(hex: string): Rgb | undefined

A #rrggbb or #rgb colour (the # optional, any case) as its channels; undefined for what is not one.

png.luminancefunctionno test imports it
function luminance(rgb: Rgb): number

A colour's relative luminance as WCAG 2 measures it, from 0 (black) to 1 (white).

Picturetype
type Picture = { readonly width: number; readonly height: number; readonly channels: 3 | 4; readonly data: Uint8Array };

A raster: its size, its channels (3 for RGB, 4 for RGBA) and its bytes, row by row, eight bits a channel.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

Rgbtypeno test imports it
type Rgb = readonly [number, number, number];

A colour's red, green and blue, each 0 to 255.

Rgbatypeno test imports it
type Rgba = readonly [number, number, number, number];

A colour's red, green, blue and alpha, each 0 to 255.

MAX_PIXELSconst
const MAX_PIXELS: number

The most pixels a picture read may have: 2^24 (16,777,216, a 4096 by 4096 square). Its RGBA is then at most 64 MiB, and the inflated data of the largest kind (16-bit RGBA) at most 128 MiB. A file that declares more is refused as too-large before anything is read.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

PngErrortype
type PngError = | { readonly kind: "signature"; readonly format: "png" | "ico" } | { readonly kind: "crc"; readonly … (571 characters)
type PngError =
  | { readonly kind: "signature"; readonly format: "png" | "ico" }
  | { readonly kind: "crc"; readonly chunk: string; readonly at: number }
  | { readonly kind: "truncated"; readonly message: string }
  | { readonly kind: "malformed"; readonly message: string }
  | { readonly kind: "unsupported"; readonly message: string }
  | { readonly kind: "interlaced" }
  | { readonly kind: "too-large"; readonly width: number; readonly height: number; readonly limit: number }
  | { readonly kind: "ico-frame"; readonly index: number; readonly error: PngError };

Why bytes are not a PNG or icon file this reader takes.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

formatPngErrorfunction
function formatPngError(e: PngError): string

A PNG error as one sentence.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

filledfunction
function filled(width: number, height: number, rgba: Rgba): Picture

A picture of one colour, RGBA. A size that is not a positive integer throws a RangeError.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

rgbOffunction
function rgbOf(p: Picture): Picture

The picture without its alpha; a picture without alpha as it is.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

rgbaOffunction
function rgbaOf(p: Picture): Picture

The picture with alpha, opaque where it had none; a picture with alpha as it is.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

readPngfunction
function readPng(bytes: Uint8Array<ArrayBufferLike>): Promise<Result<Picture, PngError>>

A PNG read into eight-bit RGBA, its filters undone and its palette and transparency applied; or why it cannot be.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

writePngfunction
function writePng(p: Picture): Promise<Uint8Array<ArrayBufferLike>>

A picture written as an eight-bit RGB or RGBA PNG, each row unfiltered, its zlib stream the platform's CompressionStream.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

premultiplyfunction
function premultiply(p: Picture): Picture

The picture with each colour channel multiplied by its alpha, rounded as Pillow rounds; a picture without alpha as it is.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

unpremultiplyfunction
function unpremultiply(p: Picture): Picture

The picture with each colour channel divided by its alpha again, as Pillow divides; a picture without alpha as it is.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

resizeChannelsfunction
function resizeChannels(p: Picture, width: number, height: number): Picture

A picture resized with Pillow's Lanczos filter in its fixed point, each channel filtered on its own (alpha too, and the colour channels without regard to it). A size that is not a positive integer throws a RangeError.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

resizefunction
function resize(p: Picture, width: number, height: number): Picture

A picture resized as Pillow resizes it with its Lanczos filter: an RGBA picture on premultiplied alpha. The same size gives it back.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

compositefunction
function composite(base: Picture, over: Picture, left: number, top: number): Picture

over laid on base with its top left corner at (left, top), as Pillow's alpha_composite lays it; what falls outside base is cut off. The result has alpha; a picture without alpha is taken as opaque.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

flatOnfunction
function flatOn(colour: Rgb, width: number, height: number, art: Picture, left: number, top: number): Picture

art laid at (left, top) on an opaque canvas of colour, the result without alpha.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

thumbnailSizefunction
function thumbnailSize(p: Picture, width: number, height: number): readonly [number, number] | undefined

The size Pillow's thumbnail gives a picture fitted in width by height, its aspect kept; undefined where it already fits.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

writeIcofunction
function writeIco(p: Picture, sizes: readonly number[]): Promise<Uint8Array<ArrayBufferLike>>

A multi-size icon file of PNG frames, as Pillow writes one: one frame for each size asked that is at most the picture's width, height and 256, smallest first, each the picture fitted in that square (thumbnailSize) and resized (resize).

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

readIcofunction
function readIco(bytes: Uint8Array<ArrayBufferLike>): Promise<Result<readonly Picture[], PngError>>

Every frame of an icon file whose frames are PNGs, in the order of its directory; or why it cannot be read.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

samePixelsfunction
function samePixels(a: Picture, b: Picture): boolean

Whether two pictures have the same size and the same RGBA pixels (a picture without alpha taken as opaque).

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

samePicturefunction
function samePicture(a: Uint8Array<ArrayBufferLike>, b: Uint8Array<ArrayBufferLike>): Promise<boolean>

Whether two PNG files, or two icon files, hold the same pictures pixel for pixel, whatever their zlib streams; false where either cannot be read.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

hexRgbfunction
function hexRgb(hex: string): Rgb | undefined

A #rrggbb or #rgb colour (the # optional, any case) as its channels; undefined for what is not one.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

luminancefunction
function luminance(rgb: Rgb): number

A colour's relative luminance as WCAG 2 measures it, from 0 (black) to 1 (white).

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.