Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

Source of release 0.45.1

0.45.1 / src / streaming.lucb

#==============================================================================================
#
#   streaming - A picture decoded a band of rows at a time
#
#   DESCRIPTION:
#       Decoding a picture whole keeps every sample as an f64: a 15000 by 24000 RGB photograph
#       is 8.6 GB before it becomes a single tile. PNG and JPEG decoders hand their rows over
#       in order as they go, and a TIFF is strips or tiles decoded one row of them at a time,
#       so a picture of these formats goes to its reader as linear-light straight RGBA f32 a
#       band of rows at a time (`stream_linear`), each band made and passed on before the next
#       is decoded. The canvas turns each band of 256 rows into a row of tiles.
#
#       A PNG or JPEG can also go as its encoded 8 or 16-bit RGBA samples (`stream_encoded`),
#       for a reader that turns codes into what it keeps through tables (`encoded_tables`)
#       rather than making floats first: what lets a document's tiles keep up with the
#       decoder when a picture opens.
#
#==============================================================================================

from luce_std import math
from luce_color import transfer
import memory
from luce_png import png
from luce_jpeg import jpeg
from luce_tiff import tiff
from luce_raster import model
from file_source import FileSource, read_source
from luce_canvas.half import to_half
from luce_raster.errors import invalid

## Receives rows `first..<first + count` of a picture as linear-light straight
## RGBA f32, `width * count * 4` samples, in order from the top. The samples
## are valid only during the call.
pub type LinearSink = func(void*?, usize, usize, f32[]) -> unit!

## Receives rows `first..<first + count` of a picture as encoded RGBA, in
## order from the top: 8-bit samples, or native-endian 16-bit ones when the
## last argument says so. The samples are valid only during the call.
pub type EncodedSink = func(void*?, usize, usize, const u8[], bool) -> unit!

## Receives a picture's first sight while its rows are still to come: the
## picture at 1/8 size, `width` by `height` 8-bit RGBA pixels (a progressive
## JPEG's first scans, an interlaced PNG's first pass). Valid only during the call.
pub type CoarseSink = func(void*?, usize, usize, const u8[]) -> unit!

## The sRGB decoding of an encoded component in 0..1.
pub func decode_srgb(value: f64) -> f64:
    return transfer.srgb_decode(math.clamp(value, 0.0, 1.0))

## Rows gathered into bands of `rows` for a sink.
struct Banding:
    var width: usize
    var height: usize
    var rows: usize
    var band: f32[]
    ## The picture row the band starts at, and how many of its rows are made.
    var top: usize
    var filled: usize
    ## Encoded 8 or 16-bit sample to linear light.
    var table: f32[]
    var sink: LinearSink
    var context: void*?

## `raster`'s picture (probed, not decoded) to `sink` in bands of `rows`,
## when it is a PNG, a JPEG or a TIFF of strips or tiles upright; false for
## any other, which must be decoded whole. A PNG or JPEG held only as its
## file's start is read from `file`.
pub func stream_linear(raster: model.Raster*, file: FileSource*?, rows: usize, sink: LinearSink, context: void*?) -> bool!:
    let named = raster.file_format
    let streams = named == "PNG" or named == "JPEG" or (named == "TIFF" and tiff.streams_by_rows(raster))
    if not streams:
        return false
    if rows == 0:
        error(invalid, "a band has at least one row")
    var banding = Banding(width = raster.width, height = raster.height, rows = rows, band = try new f32[raster.width * rows * 4] --- in memory.heap,
                          top = 0, filled = 0, table = try new f32[65536] --- in memory.heap, sink = sink, context = context)
    defer free(banding.band) in memory.heap
    defer free(banding.table) in memory.heap
    if named == "PNG":
        let deep = raster.bits == 16
        fill_table(banding.table, 65535.0 if deep else 255.0)
        try png_rows(raster, file, deep_rows if deep else byte_rows, (void*)&banding, deep)
    elif named == "JPEG":
        fill_table(banding.table, 255.0)
        try jpeg_rows(raster, file, byte_rows, (void*)&banding)
    else:
        _ = try tiff.decode_rows(raster, tiff_part, (void*)&banding)
    if banding.top + banding.filled != banding.height:
        error(invalid, "the picture ended before its last row")
    return true

## `raster`'s picture (probed, not decoded) to `sink` in bands of `rows` as
## the encoded samples its decoder makes, when it is a PNG or a JPEG; false
## for any other, which goes through `stream_linear`. One held only as its
## file's start is read from `file`.
pub func stream_encoded(raster: model.Raster*, file: FileSource*?, rows: usize, sink: EncodedSink, context: void*?, coarse: CoarseSink? = none) -> bool!:
    let named = raster.file_format
    if named != "PNG" and named != "JPEG":
        return false
    if rows == 0:
        error(invalid, "a band has at least one row")
    let deep = named == "PNG" and raster.bits == 16
    let pixel: usize = 8 if deep else 4
    var banding = EncodedBands(width = raster.width, height = raster.height, rows = rows, pixel = pixel, deep = deep, band = try new u8[raster.width * rows * pixel] --- in memory.heap,
                               top = 0, filled = 0, sink = sink, context = context)
    defer free(banding.band) in memory.heap
    if named == "PNG":
        try png_rows(raster, file, encoded_rows, (void*)&banding, deep, coarse, context)
    else:
        try jpeg_rows(raster, file, encoded_rows, (void*)&banding, coarse, context)
    if banding.top + banding.filled != banding.height:
        error(invalid, "the picture ended before its last row")
    return true

## A PNG's rows to `sink`, from its bytes held or from `file`; an interlaced
## one's first sight to `coarse` with `coarse_context`.
func png_rows(raster: const model.Raster*, file: FileSource*?, sink: png.RowSink, context: void*?, deep: bool, coarse: CoarseSink? = none, coarse_context: void*? = none) -> !:
    let options = png.DecodeOptions(max_bytes = raster.max_bytes, coarse = coarse, coarse_context = coarse_context)
    if let source = file:
        let size = source.size()
        try png.decode_rows_at(read_source, (void*)source, size, sink, context, deep, options)
        return
    try png.decode_rows(raster.encoded, sink, context, deep, options)

## A JPEG's rows to `sink` as RGBA, from its bytes held or from `file`; a
## progressive one's first sight to `coarse` with `coarse_context`.
func jpeg_rows(raster: const model.Raster*, file: FileSource*?, sink: jpeg.RowSink, context: void*?, coarse: CoarseSink? = none, coarse_context: void*? = none) -> !:
    let options = jpeg.Options(max_bytes = raster.max_bytes, coarse = coarse, coarse_context = coarse_context)
    if let source = file:
        let size = source.size()
        try jpeg.decode_rows_at(read_source, (void*)source, size, sink, context, .rgba, options)
        return
    try jpeg.decode_rows(raster.encoded, sink, context, .rgba, options)

## Each code's half float for `stream_encoded`'s samples: `color` as linear
## light from sRGB, `alpha` as coverage; 256 entries each, 65536 when `deep`.
pub func encoded_tables(deep: bool, color: u16[], alpha: u16[]) -> !:
    let codes: usize = 65536 if deep else 256
    if color.length < codes or alpha.length < codes:
        error(invalid, "a table has an entry for every code")
    let maximum = (f64)(codes - 1)
    for code in 0..<codes:
        color[code] = to_half((f32)decode_srgb((f64)code / maximum))
        alpha[code] = to_half((f32)((f64)code / maximum))

## Encoded rows gathered into bands of `rows` for a sink.
struct EncodedBands:
    var width: usize
    var height: usize
    var rows: usize
    ## Bytes a pixel: 4, or 8 for 16-bit samples.
    var pixel: usize
    var deep: bool
    var band: u8[]
    var top: usize
    var filled: usize
    var sink: EncodedSink
    var context: void*?

## A decoder's rows into the band; a full band (or the last) goes to the sink.
func encoded_rows(context: void*?, first: usize, count: usize, bytes: const u8[]) -> !:
    let banding = (EncodedBands*)(context else return)
    let line = banding.width * banding.pixel
    var at: usize = 0
    while at < count:
        if first + at != banding.top + banding.filled:
            error(invalid, "a picture's rows came out of order")
        let taken = min_rows(count - at, banding.rows - banding.filled)
        memory.copy(banding.band[banding.filled * line..], bytes[at * line..], taken * line)
        banding.filled += taken
        at += taken
        if banding.filled == banding.rows or banding.top + banding.filled == banding.height:
            try banding.sink(banding.context, banding.top, banding.filled, banding.band[..<banding.filled * line], banding.deep)
            banding.top += banding.filled
            banding.filled = 0

## `table[value]`: encoded `value` of `maximum` as linear light.
func fill_table(table: f32[], maximum: f64):
    for value in 0..<min_rows(table.length, (usize)maximum + 1):
        table[value] = (f32)decode_srgb((f64)value / maximum)

## The band's next row, to be filled; `row_made` passes it on.
func next_row(banding: Banding*, row: usize) -> f32[]!:
    if row != banding.top + banding.filled:
        error(invalid, "a picture's rows came out of order")
    let at = banding.filled * banding.width * 4
    return banding.band[at..<at + banding.width * 4]

## A row is made: a full band (or the last) goes to the sink.
func row_made(banding: Banding*) -> !:
    banding.filled += 1
    if banding.filled < banding.rows and banding.top + banding.filled < banding.height:
        return
    try banding.sink(banding.context, banding.top, banding.filled, banding.band[..<banding.width * banding.filled * 4])
    banding.top += banding.filled
    banding.filled = 0

## A decoder's 8-bit RGBA rows.
func byte_rows(context: void*?, first: usize, count: usize, bytes: const u8[]) -> !:
    let banding = (Banding*)(context else return)
    let width = banding.width
    for y in 0..<count:
        let row = try next_row(banding, first + y)
        let source = bytes[y * width * 4..<(y + 1) * width * 4]
        for x in 0..<width * 4:
            row[x] = banding.table[(usize)source[x]] if x % 4 != 3 else (f32)source[x] / 255.0
        try row_made(banding)

## A PNG's 16-bit RGBA rows, native-endian sample pairs.
func deep_rows(context: void*?, first: usize, count: usize, bytes: const u8[]) -> !:
    let banding = (Banding*)(context else return)
    let width = banding.width
    let samples = u16[]((u16*)&bytes[0], bytes.length // 2)
    for y in 0..<count:
        let row = try next_row(banding, first + y)
        let source = samples[y * width * 4..<(y + 1) * width * 4]
        for x in 0..<width * 4:
            row[x] = banding.table[(usize)source[x]] if x % 4 != 3 else (f32)source[x] / 65535.0
        try row_made(banding)

# mark: TIFF ==================================================================================

## A TIFF's rows `top..<top + part.height` (luce-tiff's `decode_rows`) made linear into the band.
func tiff_part(context: void*?, top: usize, part: const model.Raster*) -> !:
    let banding = (Banding*)(context else trap("a TIFF's rows lost their band"))
    var names = ChannelPlaces(red = -1, green = -1, blue = -1, alpha = -1)
    for channel in 0..<part.channels.length:
        names.take(part.channels[channel].name, (i64)channel)
    let kind = part.channels[0].kind
    let scale = 1.0 / model.maximum(kind)
    let encoded = kind != .float16 and kind != .float32 and kind != .float64
    let stride = part.channels.length
    for y in 0..<part.height:
        let row = try next_row(banding, top + y)
        for x in 0..<part.width:
            let at = (y * part.width + x) * stride
            row[x * 4] = linear_of(part.pixels, at, names.red, scale, encoded)
            row[x * 4 + 1] = linear_of(part.pixels, at, names.green, scale, encoded)
            row[x * 4 + 2] = linear_of(part.pixels, at, names.blue, scale, encoded)
            row[x * 4 + 3] = (f32)(part.pixels[at + (usize)names.alpha] * scale) if names.alpha >= 0 else 1.0
        try row_made(banding)

func min_rows(a: usize, b: usize) -> usize:
    return a if a < b else b

## Where each color sits within a pixel's samples; -1 when absent.
struct ChannelPlaces:
    var red: i64
    var green: i64
    var blue: i64
    var alpha: i64

    func take(name: str, channel: i64):
        if name == "Y":
            self.red = channel
            self.green = channel
            self.blue = channel
        elif name == "R":
            self.red = channel
        elif name == "G":
            self.green = channel
        elif name == "B":
            self.blue = channel
        elif name == "A":
            self.alpha = channel

func linear_of(samples: const f64[], at: usize, channel: i64, scale: f64, encoded: bool) -> f32:
    if channel < 0:
        return 0.0
    let value = samples[at + (usize)channel] * scale
    return (f32)(decode_srgb(value) if encoded else value)