dymokomi/luce-png
Source of release 0.10.1
0.10.1 / src / png / module.lucb
#==============================================================================================
#
# png - PNG decoding and encoding
#
# DESCRIPTION:
# Static PNG: every standard color type and bit depth, palettes, tRNS and Adam7, and
# the color chunks (cICP, iCCP with its profile inflated, sRGB, gAMA, cHRM).
# Decoding goes to 8-bit or 16-bit RGBA (`decode_rgba8`, `decode_rgba16`), to a
# row callback (`decode_rows`, or `decode_rows_at` reading the file in pieces), or
# to a Raster's f64 samples (`probe`, `decode`).
# Encoding takes 8- or 16-bit gray, gray-alpha, RGB or RGBA rows at once
# (`encode_rgba8`...) or pushed in bands through an `Encoder`, or a Raster.
#
# Encoding filters each row (libpng's minimum-sum heuristic) and deflates bands
# of rows on every processor as independent segments, one IDAT chunk each, joined
# with sync flushes into one valid zlib stream, as pigz does. A band's first row
# is filtered without the row above, and a private ancillary chunk `luPD` records
# the bands, so this decoder inflates, unfilters and converts them on every
# processor too. Other PNGs inflate on the calling thread while a second thread
# unfilters and converts the rows already inflated.
#
# Fragments, in ORDER:
#
# module.lucb the public API
# chunks.lucb chunk parsing, the header, palette and transparency
# color.lucb the color chunks and the ICC profile
# filters.lucb filtering and unfiltering rows
# decode.lucb parallel and sequential decoding, Adam7, output conversion
# source.lucb decoding from a file read in pieces (`decode_rows_at`)
# encode.lucb the Encoder: bands, chunks and the zlib stream around them
# work.lucb the worker threads
# apng.lucb the animation chunks: acTL, fcTL, fdAT, walked as libpng reads them
# animation.lucb Animation: an APNG's frames decoded and composited
# tests.lucb the module's tests
#
#==============================================================================================
import memory
import thread
import os
import strings
from luce_compress import flate
from luce_raster.binary import Reader, Buffer
from luce_raster.model import Raster, SampleType
from luce_raster.errors import corrupt, unsupported, invalid, limit
let signature = b"\x89PNG\r\n\x1a\n"
## A PNG's size and pixel format, from its header.
pub struct Info:
pub var width: usize
pub var height: usize
## 1, 2, 4, 8 or 16.
pub var bits: usize
## 0 gray, 2 RGB, 3 palette, 4 gray and alpha, 6 RGBA.
pub var color: usize
pub var interlaced: bool
## Whether it has alpha, from its color type or a tRNS chunk.
pub var alpha: bool
## What it says about its colors: cICP, iCCP, sRGB, gAMA and cHRM (png/color).
pub var colorimetry: Colorimetry
## Whether it is an animated PNG: an acTL chunk before the image data, read as libpng
## reads it (png/apng).
pub var animated: bool
## The frames an animation shows (acTL's count, the default image counted only when it
## is the first frame); 1 for a still PNG.
pub var frame_count: usize
## How many times the animation plays (acTL's num_plays): 0 forever.
pub var loop_count: u32
## How many times browsers play the animation in all: 0 forever, 1 for a still PNG.
pub func plays() -> u32:
return self.loop_count if self.animated else 1
## How a decode runs.
pub struct DecodeOptions:
## Worker threads, counting the caller's; 0 uses every processor.
pub var threads: usize = 0
## The most the decoder allocates besides the output.
pub var max_bytes: usize = 1073741824
## Row decodes of an interlaced picture: its first sight, Adam7's first
## pass (every eighth pixel each way, 1/8 size) as RGBA, before its rows.
pub var coarse: CoarseSink? = none
pub var coarse_context: void*? = none
## Pixel layouts: channels and bits a sample.
pub enum Format:
gray8
gray_alpha8
rgb8
rgba8
gray16
gray_alpha16
rgb16
rgba16
## Receives `rows` decoded rows starting at `first_row`, tightly packed RGBA (8-bit
## bytes, or 16-bit samples as native-endian byte pairs), on the decoding thread and
## in top-to-bottom order.
pub type RowSink = func(void*?, usize, usize, const u8[]) -> unit!
## Receives a coarse picture, `width` by `height` 8-bit RGBA pixels, on the
## decoding thread. A failure stops the decode.
pub type CoarseSink = func(void*?, usize, usize, const u8[]) -> unit!
## The header of the PNG in `data`.
pub func info(data: const u8[]) -> Info!:
var parsed = try parse(data, false)
defer parsed.close()
return parsed.info
## Fill `image`'s size, channels and format from its encoded bytes, ahead of
## `allocate` and `decode`: Y, YA, RGB or RGBA (a palette is RGB, tRNS adds alpha).
pub func probe(image: Raster*) -> !:
var parsed = try parse(image.encoded, true)
defer parsed.close()
try probed(image, &parsed)
## `probe` from the start of a file up to its first IDAT chunk (`head_bytes`
## says how much that is), for a file read in pieces later (`decode_rows_at`).
pub func probe_head(image: Raster*) -> !:
var parsed = try parse_head(image.encoded)
defer parsed.close()
try probed(image, &parsed)
## Bytes of the start of a file, whose first `data.length` are `data`, up to its
## first IDAT chunk: 0 when `data` holds them all, else how many it takes to go
## on (at least one chunk header more). Fails when the file is not a PNG.
pub func head_bytes(data: const u8[]) -> usize!:
if data.length < 8:
return 8
if (str)data[..<8] != (str)signature:
error(corrupt, "invalid PNG signature")
var at: usize = 8
while true:
if at + 8 > data.length:
return at + 8
let length = ((usize)data[at] << 24) | ((usize)data[at + 1] << 16) | ((usize)data[at + 2] << 8) | (usize)data[at + 3]
if (str)data[at + 4..<at + 8] == "IDAT" or (str)data[at + 4..<at + 8] == "IEND":
return 0
at += 12 + length
func probed(image: Raster*, parsed: const Parsed*) -> !:
let i = parsed.info
image.width = i.width
image.height = i.height
image.bits = i.bits
image.photo = (u64)i.color
image.interlaced = i.interlaced
image.palette = parsed.palette
image.transparency = parsed.transparency
let base = 3 if i.color == 3 else source_channels(i.color)
try image.standard(base + (1 if parsed.transparency.length > 0 else 0), .uint16 if i.bits == 16 else .uint8)
_ = try image.validate()
image.file_format = "PNG"
## Decode a probed and allocated `image` into its f64 samples.
pub func decode(image: Raster*) -> !:
if image.pixels.length != image.width * image.height * image.channels.length:
error(invalid, "PNG raster pixels are not allocated")
var target = Target(doubles = image.pixels, channels = image.channels.length)
try decode_into(image.encoded, &target, DecodeOptions(max_bytes = image.max_bytes))
## Decode into `out` as 8-bit RGBA, `width * height * 4` bytes. 16-bit samples round
## to the nearest 8-bit value.
pub func decode_rgba8(data: const u8[], out: u8[], options: DecodeOptions = DecodeOptions()) -> !:
let i = try info(data)
if out.length < i.width * i.height * 4:
error(invalid, "PNG output buffer is smaller than the picture")
var target = Target(bytes = out)
try decode_into(data, &target, options)
## Decode into `out` as 16-bit RGBA, `width * height * 4` samples; 8-bit samples
## scale by 257.
pub func decode_rgba16(data: const u8[], out: u16[], options: DecodeOptions = DecodeOptions()) -> !:
let i = try info(data)
if out.length < i.width * i.height * 4:
error(invalid, "PNG output buffer is smaller than the picture")
var target = Target(words = out)
try decode_into(data, &target, options)
## Decode in bands of whole rows, each handed to `sink` with `context`, as RGBA with
## 8 bits (`deep` false) or 16 bits a sample.
pub func decode_rows(data: const u8[], sink: RowSink, context: void*?, deep: bool = false, options: DecodeOptions = DecodeOptions()) -> !:
var target = Target(sink = sink, context = context, deep = deep)
try decode_into(data, &target, options)
## How an encode runs.
pub struct EncodeOptions:
## zlib level 0..9; 6 is zlib's default, 1 the fastest, 0 stores.
pub var level: i32 = 6
## Row filtering: -1 picks per row by libpng's minimum sum of absolute
## differences, 0..4 always uses None, Sub, Up, Average or Paeth.
pub var filter: i32 = -1
## Worker threads, counting the caller's; 0 uses every processor.
pub var threads: usize = 0
## Rows a band (the unit compressed and decoded in parallel); 0 for about a
## megabyte of pixels.
pub var band_rows: usize = 0
## An ICC profile to embed as an iCCP chunk (zlib-compressed), telling readers
## the pixels' color space; empty for none.
pub var icc_profile: const u8[]
## Encode `width` x `height` RGBA pixels (row after row) as a PNG appended to `output`.
pub func encode_rgba8(pixels: const u8[], width: usize, height: usize, output: Buffer*, options: EncodeOptions = EncodeOptions()) -> !:
var encoder = try Encoder.begin(width, height, .rgba8, output, options)
defer encoder.close()
try encoder.write_rows(pixels, height)
try encoder.finish()
## Encode 16-bit RGBA samples.
pub func encode_rgba16(pixels: const u16[], width: usize, height: usize, output: Buffer*, options: EncodeOptions = EncodeOptions()) -> !:
var encoder = try Encoder.begin(width, height, .rgba16, output, options)
defer encoder.close()
try encoder.write_rows16(pixels, height)
try encoder.finish()
## Encode a Raster's uint8 or uint16 samples, 1 to 4 channels.
pub func encode(image: const Raster*, output: Buffer*, options: EncodeOptions = EncodeOptions()) -> !:
let nc = image.channels.length
if nc == 0 or nc > 4:
error(unsupported, "PNG supports one to four channels")
let kind = image.channels[0].kind
if kind != .uint8 and kind != .uint16:
error(unsupported, "PNG requires uint8 or uint16 channels")
for c in image.channels:
if c.kind != kind:
error(unsupported, "PNG requires matching channel sample types")
if image.pixels.length != image.width * image.height * nc:
error(invalid, "PNG raster pixels are not allocated")
let deep = kind == .uint16
let formats: Format[4] = [.gray8, .gray_alpha8, .rgb8, .rgba8]
let deep_formats: Format[4] = [.gray16, .gray_alpha16, .rgb16, .rgba16]
var encoder = try Encoder.begin(image.width, image.height, deep_formats[nc - 1] if deep else formats[nc - 1], output, options)
defer encoder.close()
# Samples to integers a few rows at a time.
let batch: usize = 32
let row = image.width * nc
let top = 65535.0 if deep else 255.0
let bytes = try new u8[batch * row] --- in memory.heap
defer free(bytes) in memory.heap
let words = try new u16[batch * row] --- in memory.heap
defer free(words) in memory.heap
var y: usize = 0
while y < image.height:
let rows = batch if y + batch <= image.height else image.height - y
let samples = image.pixels[y * row..<(y + rows) * row]
for i in 0..<samples.length:
# 2^52 + 2^51 added leaves a whole number in the low bits, and gives the
# value back exactly only if it was whole: no float-to-integer call.
let value = samples[i]
let t = value + 6755399441055744.0
if not (value >= 0.0 and value <= top) or t - 6755399441055744.0 != value:
error(invalid, "PNG sample is outside its integer range")
let whole = t.bits() -% 0x4338000000000000
if deep:
words[i] = (u16)whole
else:
bytes[i] = (u8)whole
if deep:
try encoder.write_rows16(words[..<rows * row], rows)
else:
try encoder.write_rows(bytes[..<rows * row], rows)
y += rows
try encoder.finish()
func source_channels(color: usize) -> usize:
return 3 if color == 2 else 2 if color == 4 else 4 if color == 6 else 1