Luce packages
LuceLuce BaseLuciaOS

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