dymokomi/luce-image
Source of release 0.45.0
#==============================================================================================
#
# 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)