pngnamespacenamespace pngPictures 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, ...] } }pngnamespacenamespace pngpng.Picturetypeno test imports ittype 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 ittype Rgb = readonly [number, number, number];A colour's red, green and blue, each 0 to 255.
png.Rgbatypeno test imports ittype Rgba = readonly [number, number, number, number];A colour's red, green, blue and alpha, each 0 to 255.
png.MAX_PIXELSconstno test imports itconst MAX_PIXELS: numberThe 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 ittype 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 itfunction formatPngError(e: PngError): stringA PNG error as one sentence.
png.filledfunctionno test imports itfunction filled(width: number, height: number, rgba: Rgba): PictureA picture of one colour, RGBA. A size that is not a positive integer throws a RangeError.
png.rgbOffunctionno test imports itfunction rgbOf(p: Picture): PictureThe picture without its alpha; a picture without alpha as it is.
png.rgbaOffunctionno test imports itfunction rgbaOf(p: Picture): PictureThe picture with alpha, opaque where it had none; a picture with alpha as it is.
png.readPngfunctionno test imports itfunction 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 itfunction 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 itfunction premultiply(p: Picture): PictureThe picture with each colour channel multiplied by its alpha, rounded as Pillow rounds; a picture without alpha as it is.
png.unpremultiplyfunctionno test imports itfunction unpremultiply(p: Picture): PictureThe picture with each colour channel divided by its alpha again, as Pillow divides; a picture without alpha as it is.
png.resizeChannelsfunctionno test imports itfunction resizeChannels(p: Picture, width: number, height: number): PictureA 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 itfunction resize(p: Picture, width: number, height: number): PictureA 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 itfunction composite(base: Picture, over: Picture, left: number, top: number): Pictureover 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 itfunction flatOn(colour: Rgb, width: number, height: number, art: Picture, left: number, top: number): Pictureart laid at (left, top) on an opaque canvas of colour, the result without alpha.
png.thumbnailSizefunctionno test imports itfunction thumbnailSize(p: Picture, width: number, height: number): readonly [number, number] | undefinedThe size Pillow's thumbnail gives a picture fitted in width by height, its aspect kept; undefined where it already fits.
png.writeIcofunctionno test imports itfunction 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 itfunction 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 itfunction samePixels(a: Picture, b: Picture): booleanWhether two pictures have the same size and the same RGBA pixels (a picture without alpha taken as opaque).
png.samePicturefunctionno test imports itfunction 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 itfunction hexRgb(hex: string): Rgb | undefinedA #rrggbb or #rgb colour (the # optional, any case) as its channels; undefined for what is not one.
png.luminancefunctionno test imports itfunction luminance(rgb: Rgb): numberA colour's relative luminance as WCAG 2 measures it, from 0 (black) to 1 (white).
Picturetypetype 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.
Rgbtypeno test imports ittype Rgb = readonly [number, number, number];A colour's red, green and blue, each 0 to 255.
Rgbatypeno test imports ittype Rgba = readonly [number, number, number, number];A colour's red, green, blue and alpha, each 0 to 255.
MAX_PIXELSconstconst MAX_PIXELS: numberThe 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.
PngErrortypetype 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.
formatPngErrorfunctionfunction formatPngError(e: PngError): stringA PNG error as one sentence.
filledfunctionfunction filled(width: number, height: number, rgba: Rgba): PictureA picture of one colour, RGBA. A size that is not a positive integer throws a RangeError.
rgbOffunctionfunction rgbOf(p: Picture): PictureThe picture without its alpha; a picture without alpha as it is.
rgbaOffunctionfunction rgbaOf(p: Picture): PictureThe picture with alpha, opaque where it had none; a picture with alpha as it is.
readPngfunctionfunction 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.
writePngfunctionfunction 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.
premultiplyfunctionfunction premultiply(p: Picture): PictureThe picture with each colour channel multiplied by its alpha, rounded as Pillow rounds; a picture without alpha as it is.
unpremultiplyfunctionfunction unpremultiply(p: Picture): PictureThe picture with each colour channel divided by its alpha again, as Pillow divides; a picture without alpha as it is.
resizeChannelsfunctionfunction resizeChannels(p: Picture, width: number, height: number): PictureA 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.
resizefunctionfunction resize(p: Picture, width: number, height: number): PictureA picture resized as Pillow resizes it with its Lanczos filter: an RGBA picture on premultiplied alpha. The same size gives it back.
compositefunctionfunction composite(base: Picture, over: Picture, left: number, top: number): Pictureover 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.
flatOnfunctionfunction flatOn(colour: Rgb, width: number, height: number, art: Picture, left: number, top: number): Pictureart laid at (left, top) on an opaque canvas of colour, the result without alpha.
thumbnailSizefunctionfunction thumbnailSize(p: Picture, width: number, height: number): readonly [number, number] | undefinedThe size Pillow's thumbnail gives a picture fitted in width by height, its aspect kept; undefined where it already fits.
writeIcofunctionfunction 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).
readIcofunctionfunction 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.
samePixelsfunctionfunction samePixels(a: Picture, b: Picture): booleanWhether two pictures have the same size and the same RGBA pixels (a picture without alpha taken as opaque).
samePicturefunctionfunction 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.
hexRgbfunctionfunction hexRgb(hex: string): Rgb | undefinedA #rrggbb or #rgb colour (the # optional, any case) as its channels; undefined for what is not one.
luminancefunctionfunction luminance(rgb: Rgb): numberA colour's relative luminance as WCAG 2 measures it, from 0 (black) to 1 (white).