photonimage

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package photonimage is the pixel pipeline Photon (@silvia-odwyer/photon 0.3.3, Rust) runs, ported to Go: the PNG encoder behind `PhotonImage.get_bytes()` (EncodePNG), the JPEG encoder behind `get_bytes_jpeg(quality)` (EncodeJPEG) and the Lanczos3 `resize` (ResizeLanczos3), all byte for byte. The durable image processor (durable/images) and the coding agent's image path (internal/imageprocessing) use it, so both reproduce Photon's pixels and the PNG and JPEG bytes, and with them Photon's sizes, which decide what fits a byte limit and which of PNG and JPEG a resize returns. Decode (JPEG and WebP: DecodeJPEG, DecodeWebP) is the decoding Photon's `new_from_byteslice` runs.

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrPNGNoPixels = errors.New("photonimage: png: image has no pixels")

ErrPNGNoPixels is the exception Photon's `get_bytes()` throws for an image with a width or a height of zero: the png crate's encoder refuses it (`ZeroWidth`, `ZeroHeight`, encoder.rs:431-437), and the `unwrap` after it traps the WebAssembly instance.

Functions

func Decode

func Decode(data []byte) (image.Image, error)

Decode decodes the bytes Photon's `PhotonImage.new_from_byteslice` decodes: image 0.24.9 `load_from_memory` guesses the format from the magic bytes (guess_format, io/free_functions.rs:266-312) and decodes it, then Photon converts the result with `to_rgba8`. Every format Photon enables is decoded by a port of the Rust decoder that gives its pixels or its error. No Go decoder is registered or used: they accept other files than Photon and give other pixels.

PNG       DecodePNG       image 0.24.9, over png 0.17.14 and fdeflate 0.3.6
JPEG      DecodeJPEG      jpeg-decoder 0.3.1
WebP      DecodeWebP      image 0.24.9
BMP       DecodeBMP       image 0.24.9
GIF       DecodeGIF       image 0.24.9, over gif 0.13.1 and weezl 0.1.8
TIFF      DecodeTIFF      tiff 0.9.1
DDS       DecodeDDS       image 0.24.9 (DXT1, DXT3 and DXT5)
ICO       DecodeICO       image 0.24.9, over its BMP decoder and the png 0.17.14 reader
Radiance  DecodeHDR       image 0.24.9
PNM       DecodePNM       image 0.24.9
farbfeld  DecodeFarbfeld  image 0.24.9

Bytes that no signature of guess_format matches are an error, as in Photon (TGA has no signature, io/free_functions.rs:295, and AVIF, OpenEXR and QOI are not compiled into Photon's wasm). The result is not premultiplied.

The cases follow the order of guess_format's table, whose first matching signature wins; no signature is a prefix of another, so the order only documents it.

func DecodeBMP

func DecodeBMP(data []byte) (*image.NRGBA, error)

DecodeBMP returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for a BMP file: image 0.24.9's `BmpDecoder::new` (codecs/bmp/decoder.rs) driven by `load_from_memory`, then `to_rgba8`. The file header's size and reserved fields are not read, the bitmap is read from the header's data offset, and every layout the decoder knows is accepted: the core header, the BITMAPINFOHEADER and its V2 to V5 extensions with the palette, RLE4 and RLE8, 16-bit, 24-bit and 32-bit colour, bitfields, top-down bitmaps. The result has an alpha channel only through an alpha bitfield mask. Everything else is an error, as is an image of more than 512 MiB of RGB8 (or RGBA8) or whose buffer length overflows wasm32's `usize`.

func DecodeDDS

func DecodeDDS(data []byte) (*image.NRGBA, error)

DecodeDDS returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for a DDS file: image 0.24.9's DdsDecoder (codecs/dds.rs) over its DxtDecoder (codecs/dxt.rs), as `to_rgba8` converts the Rgb8 (DXT1) or Rgba8 (DXT3, DXT5) it reports. Only the first level of DXT1, DXT3 and DXT5 (and BC1, BC2 and BC3 through the DX10 header) is read; any other pixel format, FourCC or DXGI format is an error, as are a width or height that is not a multiple of four (zero is one), a file without every block of the first level, an image of more than 2^29 bytes (imageMaxAlloc), and an empty image whose RGBA buffer length overflows wasm32's `usize` (checkRGBAConversion).

func DecodeFarbfeld

func DecodeFarbfeld(data []byte) (*image.NRGBA, error)

DecodeFarbfeld returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for a farbfeld file: image 0.24.9's FarbfeldDecoder (codecs/farbfeld.rs:38-216, Rgba16 as `to_rgba8` makes RGBA8 of it: every sample `(v + 128) / 257`, color.rs:408-421). The header is the magic and the two big endian dimensions; a file without every sample is an error (read_exact), bytes after the samples are ignored. An image of more than 2^29 bytes (width * height * 8, image's default allocation limit, imageMaxAlloc) is an error, as is an empty image whose RGBA buffer length overflows wasm32's `usize` (checkRGBAConversion).

func DecodeGIF

func DecodeGIF(data []byte) (*image.NRGBA, error)

DecodeGIF returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for a GIF file: the first frame of image 0.24.9's `GifDecoder` over the gif crate 0.13.1, on a logical screen of transparent black. The frame is placed at its offset when it does not fill the width of the screen; what is outside the frame is transparent. A frame without pixels is an error, as is a file without a frame, a screen of more than 512 MiB of RGBA, and every file the crate refuses.

func DecodeHDR

func DecodeHDR(data []byte) (*image.NRGBA, error)

DecodeHDR returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for a Radiance HDR file: image 0.24.9's HdrAdapter (codecs/hdr/decoder.rs, strict mode as `load_decoder` calls `HdrAdapter::new`), whose colour type is Rgb8: the RGBE pixels are converted by `Rgbe8Pixel::to_ldr` (`(exp2(e - 136) * c) ** 2.2 * 255 + 0.5` in f32 with libm's powf and exp2f) and `to_rgba8` adds an opaque alpha. Only the orientation `-Y height +X width` is accepted, with the 32-bit_rle_rgbe FORMAT.

What the decoder rejects is what it rejects: a signature line, header lines until an empty line (`FORMAT=` other than 32-bit_rle_rgbe, unparsable EXPOSURE, PIXASPECT and COLORCORR values and a COLORCORR with more than three numbers are errors in strict mode), the dimensions line, and scanlines (new-style RLE, flat or old-style RLE) that are cut or run past the width. An image of more than 2^29 bytes as Rgb8 (width * height * 3) is an error (imageMaxAlloc), and an image with no pixels reads no scanline.

func DecodeICO

func DecodeICO(data []byte) (*image.NRGBA, error)

DecodeICO returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for an ICO file: image 0.24.9's IcoDecoder (codecs/ico/decoder.rs) over the entry with the highest (bits per pixel, area) (the last of equals), as `to_rgba8` converts it. The type word of the directory is not read, only the entries up to the count.

An entry that starts with the PNG signature is a PNG, decoded as the png crate does (pngdecode.go), which must be 8-bit RGBA after its EXPAND transformation (RGBA, or RGB or palette with a tRNS chunk) and the size the entry names (compared up to 256); anything else is a bitmap (BmpDecoder in ICO format, bmpDecoder with noFileHeader and addAlpha), with an AND mask that makes pixels transparent when the entry's length leaves room for one. A bitmap of more than 2^29 bytes of RGBA (width * height / 2 * 4) or an empty image whose RGBA buffer length overflows wasm32's `usize` is an error, as is every other file image rejects.

func DecodeJPEG

func DecodeJPEG(data []byte) (img *image.NRGBA, err error)

DecodeJPEG returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for a JPEG: the pixels of jpeg-decoder 0.3.1 as image 0.24.9 hands them to `DynamicImage::to_rgba8` (grayscale as gray with alpha 255, three components as RGB, four as CMYK or YCCK converted to RGB by the image crate's cmyk_to_rgb, 16-bit lossless grayscale scaled to 8 bits), and an error exactly where Photon throws: the formats jpeg-decoder rejects (arithmetic coding, hierarchical and differential frames, DNL, 12-bit samples, component counts other than 1, 3 and 4, subsampling ratios that are not integers), corrupt or truncated data, and an image whose decoded size exceeds the 512 MiB of image's default limits. A progressive JPEG that lacks scans is decoded from the coefficients it has, as jpeg-decoder does.

The memory an input can ask for is the one the Rust decoder asks for: planes and coefficients of the frame header's size, which the 512 MiB limit on width * height * bytes per pixel bounds (about 1.5 GiB at most for the progressive coefficients, planes and output together); the 4 GiB address space of the wasm module, where Photon's allocation would fail first, is not emulated.

Example
var b jdcBuilder
s := jdcNewSpec(2, 2, [][2]uint8{{1, 1}}, []uint8{1}, 90)
s.fillImage(b.image("flat-white", 2, 2), "gray")
s.scans = jdcSeqInterleaved(1)
img, err := DecodeJPEG(s.build())
fmt.Println(img.Rect, err)
Output:
(0,0)-(2,2) <nil>

func DecodePNG

func DecodePNG(data []byte) (img *image.NRGBA, err error)

DecodePNG decodes a PNG file as Photon does: image 0.24.9 `load_from_memory` gives the bytes to `PngDecoder::with_limits(r, Limits::default())` (codecs/png.rs:119-199), which reads the image with the png crate 0.17.14 under the EXPAND transformation (the version the wasm of @silvia-odwyer/photon and photon-node embeds), and Photon converts the result with `to_rgba8`. The port follows the crate's streaming decoder (decoder/stream.rs), its reader (decoder/mod.rs, transform.rs, transform/palette.rs, adam7.rs, interlace_info.rs) and fdeflate 0.3.6 (pngdecode_inflate.go) step by step, so that it accepts the files the crate accepts and gives their pixels: text chunks are skipped, an ancillary chunk with a bad checksum is skipped, a critical one is an error; only the first image of an animated PNG is decoded (the default image: the IDAT data, or the fdAT data of the first fcTL when there is no IDAT chunk); the byte after the image data is not looked at but the header of the chunk after it must be there; the checksum of the zlib stream is not verified; the limits of the crate (512 MiB, `Limits::bytes`) are accounted for the buffers of the chunks, the palette, the transparency, the ICC profile and the row, in `usize` of wasm32.

func DecodePNM

func DecodePNM(data []byte) (*image.NRGBA, error)

DecodePNM returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for a PNM file: image 0.24.9's PnmDecoder (codecs/pnm/decoder.rs, header.rs), P1 to P7, and `to_rgba8` of the colour type it reports (L8 for P1 and P4 bitmaps and 8-bit graymaps, L16, Rgb8, Rgb16).

The details of the decoder are kept: a comment in the preamble ends at the newline, which is not a separator, so `1#c\n2` is the number 12; the PAM header lines are split by the position of their first whitespace in the line before it is trimmed; samples of an 8-bit image that are above the maxval are scaled and saturate, those of a bitmap are inverted (1 is black); a maxval other than 255 or 65535 scales every sample by `round(v * (255 | 65535) / maxval)` in f32. An image of more than 2^29 bytes in the colour type is an error (imageMaxAlloc), as is an empty image whose RGBA buffer length overflows wasm32's `usize` (checkRGBAConversion).

func DecodeTIFF

func DecodeTIFF(data []byte) (img *image.NRGBA, err error)

DecodeTIFF returns the RGBA8 pixels Photon's `PhotonImage.new_from_byteslice(data).get_raw_pixels()` returns for a TIFF: tiff 0.9.1 (the decoder of image 0.24.9's `TiffDecoder`, which Photon enables) over the first image of the file, as `to_rgba8` converts it. image's `guess_format` (io/free_functions.rs:268-312) finds a TIFF by "II*\0" or "MM\0*" (so BigTIFF, "II+\0", is no TIFF there), which is what Decode routes here.

What the decoder accepts is what `TiffDecoder::new` and `read_image` do: 8- and 16-bit grayscale (BlackIsZero and WhiteIsZero), RGB and RGBA (RGB photometric with three or four samples; ExtraSamples is not read) and 8-bit CMYK (converted to RGB by image's cmyk_to_rgb), unsigned samples only; compression none, LZW, PackBits, Deflate (zlib, tag 8 and 0x80B2) and JPEG (tag 7, with or without JPEGTables); the horizontal predictor; strips and tiles, chunky or planar (the first plane only: a planar RGB image panics in image's `copy_from_slice`, a planar CMYK image gives the pixels of the first plane read as CMYK); both byte orders. Palette, bilevel, 1- to 7-bit, 12-bit, 32-bit and floating point images, YCbCr, CIELab, transparency masks, the floating point predictor, Fax, old-style JPEG and anything else are errors, as are the corrupt files tiff reports an error for and the images whose decoded size is over the 512 MiB of image's default limits (see tiffLimits).

The 4 GiB address space of the wasm module, where Photon's allocation would fail first, is not emulated; the limits keep the memory an input can ask for to what the Rust decoder asks for.

func DecodeWebP

func DecodeWebP(data []byte) (img *image.NRGBA, err error)

DecodeWebP decodes a WebP file to the RGBA8 pixels (not premultiplied) that Photon's `PhotonImage.new_from_byteslice(bytes)` followed by `get_raw_pixels()` returns, and fails exactly where Photon throws. Photon (photon-rs 0.3.3 lib.rs:93-105) calls image 0.24.9 `load_from_memory(bytes).unwrap()` and then `to_rgba8()`; the format is guessed from the first bytes (a file that starts with "RIFF" is WebP, io/free_functions.rs:271), `WebPDecoder::new(..)` reads the file (codecs/webp/decoder.rs:131-137) and `DynamicImage::from_decoder` asks it for the pixels. This is that decoder, ported from image 0.24.9 (crates.io image-0.24.9.crate, the version Photon's wasm embeds):

  • decoder.rs (cited below as decoder.rs): the RIFF container, the three kinds of image (VP8, VP8L, VP8X), the color types;
  • extended.rs: VP8X, the alpha chunk (the ALPH chunk of a lossy image), animation (the first frame of an animated file is what `load_from_memory` returns, composed onto the canvas when it does not fill it);
  • webpdecode_vp8.go: the lossy decoder vp8.rs, loop_filter.rs, transform.rs;
  • webpdecode_lossless.go: the lossless decoder lossless.rs, huffman.rs, lossless_transform.rs.

The pixels of a lossy image are YUV 4:2:0 converted by the 8-bit recommendation of Microsoft with each chroma sample repeated over its 2x2 block, they differ from what golang.org/x/image/webp (and libwebp) produce; the lossless decoder differs in the corner cases of malformed files. The limits are those of Photon: an image whose RGB or RGBA8 would take more than 512 MiB (image::Limits::default().max_alloc, io/mod.rs:63-72) is an error, and so is every panic of the Rust code (an index out of bounds, an unwrap): a Go runtime error of this package is returned as an error.

func EncodeJPEG

func EncodeJPEG(img *image.NRGBA, quality uint8) ([]byte, error)

EncodeJPEG is img as the JPEG Photon's `get_bytes_jpeg(quality)` writes: baseline, 8-bit, three components without chroma subsampling, the standard Huffman tables, the quantization tables of quality scaled the libjpeg way, a JFIF 1.02 header with a pixel aspect ratio of 1, and the alpha channel dropped. quality is Photon's `u8`. It fails where Photon panics: a side over 65535 (encoder.rs:518-527) and a coefficient the standard Huffman tables cannot code (encoder.rs:222-224).

func EncodePNG

func EncodePNG(img *image.NRGBA) ([]byte, error)

EncodePNG is img as an RGBA 8-bit PNG: the signature, IHDR, one IDAT chunk and IEND (png encoder.rs write_image_data with Compression::Fast). An image with no pixels is ErrPNGNoPixels, as Photon throws for it.

func ResizeLanczos3

func ResizeLanczos3(src *image.NRGBA, width, height int) *image.NRGBA

ResizeLanczos3 is Photon's `resize(image, width, height, SamplingFilter.Lanczos3)` (packages/durable/src/images/index.ts:102, and image-resize-core.ts tryEncodings in the coding agent): the image crate 0.24.9 `imageops::resize` with its Lanczos3 filter. It scales the rows first, into 32-bit floats, then the columns, with the weights, the window and the f32 arithmetic of that code, so the pixels are Photon's own. The four channels are filtered as stored, not premultiplied. An image already of the requested size is returned as a copy.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL