Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

Source of release 0.45.1

0.45.1 / src / image / module.lucb

#==============================================================================================
#
#   image - The owning Image API
#
#   DESCRIPTION:
#       A Pillow-style image over the format packages (luce-png, luce-jpeg, luce-tiff,
#       luce-exr, luce-heic, luce-raw, luce-psd through them, and SVG through luce-svg):
#       opened lazily, loaded on first use, saved atomically. Codec code is entirely Luce
#       Base. Fragments, in ORDER:
#
#       module.lucb    Image: opening, loading, samples, metadata, saving
#       pixels.lucb    8-bit and linear-light RGBA out and in, streamed in bands
#       edit.lucb      copy, crop, channels, convert and resize
#
#==============================================================================================

import c as c_api
from luce_std import files
import interop
import memory
from luce_canvas import pool
from luce_std import math
from luce_color import transfer
import strings
import os
from luce_raster import model
from luce_png import png
from luce_jpeg import jpeg
from luce_tiff import tiff
from luce_exr import exr
from luce_raw import raw
from luce_heic import heic
import parallel
from luce_svg.render import is_svg, render_svg
from streaming import LinearSink, EncodedSink, CoarseSink, stream_linear, stream_encoded, decode_srgb
from file_source import FileSource, read_head
from luce_raster.binary import Buffer
from luce_raster.errors import invalid, unsupported, limit

pub type SampleType = model.SampleType

pub struct Pixel:
    pub let r: f64 = 0.0
    pub let g: f64 = 0.0
    pub let b: f64 = 0.0
    pub let a: f64 = 255.0

func check_path(path: str) -> !:
    if path.length == 0 or strings.contains(path, "\0"):
        error(invalid, "path is empty or contains a NUL byte")

## Probe `raster`'s encoded bytes: the file whole, or when `head` its start
## alone (file_source), which a PNG or JPEG's probe needs no more than.
func probe(raster: model.Raster*, head: bool = false) -> !:
    if raster.encoded.length < 4:
        error(invalid, "image signature is truncated")
    let data = raster.encoded
    if data[0] == 137:
        if raster.frame != 0:
            error(invalid, "PNG has one frame")
        if head:
            try png.probe_head(raster)
        else:
            try png.probe(raster)
    elif data[0] == 255 and data[1] == 216:
        if raster.frame != 0:
            error(invalid, "JPEG has one frame")
        try jpeg.probe(raster)
    elif data[0] == 118 and data[1] == 47:
        try exr.probe(raster)
    elif heic.is_heic(data):
        try heic.probe(raster)
    elif raw.detect(data) or raw.recognize(data):
        # Camera raws before TIFF: most of them are TIFF files underneath (CR3 is
        # ISO media, RAF and CRW their own). One luce-raw knows but cannot develop
        # yet says so, rather than being read as a TIFF.
        try raw.probe(raster)
    elif (data[0] == 'I' and data[1] == 'I') or (data[0] == 'M' and data[1] == 'M'):
        try tiff.probe(raster)
    else:
        error(unsupported, "unrecognized image signature")

## Whether a probed file is a camera raw luce-raw develops.
func is_raw_format(name: str) -> bool:
    for format_name in ["DNG", "CR2", "CR3", "NEF", "ARW", "ORF", "RW2", "PEF", "RAF"]:
        if name == format_name:
            return true
    return false

func configure_mode(raster: model.Raster*, mode: str) -> !:
    let nc: usize = 3 if mode == "RGB" or mode == "RGBF" else 4 if mode == "RGBA" or mode == "RGBAF" else 2 if mode == "LA" else 1
    if mode != "L" and mode != "LA" and mode != "RGB" and mode != "RGBA" and mode != "I;16" and mode != "I" and mode != "F" and mode != "RGBF" and mode != "RGBAF":
        error(invalid, "unsupported image mode")
    let kind = SampleType.uint16 if mode == "I;16" else SampleType.uint32 if mode == "I" else SampleType.float32 if mode == "F" or mode == "RGBF" or mode == "RGBAF" else SampleType.uint8
    try raster.standard(nc, kind)

pub struct Image:
    var raster: model.Raster
    var threads: usize = 4
    var active_workers: usize
    var closed: bool
    ## A PNG or JPEG opened from its file's start alone (file_source): its
    ## bands decode from the file, which must stay `file_size` bytes.
    var head_only: bool
    var file_size: u64

    func init():
        self.raster = model.Raster()
        self.threads = 4
        self.active_workers = 0
        self.closed = false
        self.head_only = false
        self.file_size = 0

    static func own(raster: model.Raster, threads: usize = 4) -> interop.Reference[Image]!:
        var reservation = try interop.Reservation[Image](image_type)
        errdefer reservation.cancel()
        let native = try new Image() in memory.heap
        native.raster = raster
        native.threads = threads
        return reservation.publish(native, memory.heap)

    func ensure_open() -> !:
        if self.closed:
            error(invalid, "image is closed")

    ## Read the file now (a large PNG or JPEG only as far as its probe needs,
    ## the rest read in pieces as it decodes); decode pixels lazily on
    ## load/access/save.
    pub static func open(path: str, threads: usize = 4, frame: usize = 0, max_bytes: usize = 4294967296, max_pixels: usize = 268435456) -> interop.Reference[Image]!:
        try check_path(path)
        if threads < 1 or threads > 64:
            error(invalid, "thread count must be in 1-64")
        if is_svg(path):
            # Drawn rather than decoded: vector artwork at a size fit to edit.
            let rendered = try render_svg(path, max_bytes, max_pixels)
            defer free(rendered.pixels) in memory.heap
            return try Image.from_linear_rgba(rendered.width, rendered.height, rendered.pixels)
        var raster = model.Raster(max_bytes = max_bytes, max_pixels = max_pixels, frame = frame)
        errdefer raster.close()
        with memory.heap:
            raster.path = try strings.copy(path)
        var size: u64 = 0
        raster.encoded = try read_head((c_api.str)raster.path, max_bytes, &size)
        let head_only = (u64)raster.encoded.length < size
        try probe(&raster, head_only)
        let opened = try Image.own(raster, threads)
        opened.value().head_only = head_only
        opened.value().file_size = size
        return opened

    ## As `open`, from encoded bytes held in memory; the bytes are copied.
    pub static func open_bytes(data: const u8[], threads: usize = 4, frame: usize = 0, max_bytes: usize = 4294967296, max_pixels: usize = 268435456) -> interop.Reference[Image]!:
        if threads < 1 or threads > 64 or data.length > max_bytes:
            error(invalid, "invalid threads or encoded byte limit")
        var raster = model.Raster(max_bytes = max_bytes, max_pixels = max_pixels, frame = frame)
        errdefer raster.close()
        raster.encoded = try new u8[data.length] --- in memory.heap
        memory.copy(raster.encoded, data, data.length)
        try probe(&raster)
        return try Image.own(raster, threads)

    ## A new image in a Pillow mode ("L", "LA", "RGB", "RGBA", "I;16", "I", "F",
    ## "RGBF", "RGBAF"), every pixel `color` or opaque black.
    pub static func create(mode: str, width: usize, height: usize, color: Pixel? = none, max_bytes: usize = 4294967296) -> interop.Reference[Image]!:
        var raster = model.Raster(width = width, height = height, max_bytes = max_bytes)
        errdefer raster.close()
        try configure_mode(&raster, mode)
        try raster.allocate()
        let pixel = color else Pixel(a = model.maximum(raster.channels[0].kind))
        for i in 0..<width * height:
            for c in 0..<raster.channels.length:
                let name = raster.channels[c].name
                raster.pixels[i * raster.channels.length + c] = pixel.a if name == "A" else pixel.g if name == "G" else pixel.b if name == "B" else pixel.r
        return try Image.own(raster)

    ## Named channels are used for AOVs and Cryptomatte; default storage is FLOAT.
    pub static func create_channels(width: usize, height: usize, names: const str[], kind: SampleType = .float32, max_bytes: usize = 4294967296) -> interop.Reference[Image]!:
        var raster = model.Raster(width = width, height = height, max_bytes = max_bytes)
        errdefer raster.close()
        for name in names:
            try raster.channel(name, kind)
        try raster.allocate()
        return try Image.own(raster)

    pub func width() -> usize!:
        try self.ensure_open()
        return self.raster.width

    pub func height() -> usize!:
        try self.ensure_open()
        return self.raster.height

    ## (width, height).
    pub func size() -> (usize, usize)!:
        try self.ensure_open()
        return (self.raster.width, self.raster.height)

    ## The data window's top-left: EXR's offset, zero for other formats.
    pub func origin() -> (i64, i64)!:
        try self.ensure_open()
        return (self.raster.xmin, self.raster.ymin)

    ## The format the image was read from: "PNG", "JPEG", "TIFF" or "EXR"; empty when created.
    pub func file_format() -> str!:
        try self.ensure_open()
        return self.raster.file_format

    ## How many frames (TIFF pages, EXR parts) the file holds.
    pub func n_frames() -> usize!:
        try self.ensure_open()
        return self.raster.frames

    ## The frame now selected; `seek` changes it.
    pub func tell() -> usize!:
        try self.ensure_open()
        return self.raster.frame

    pub func channel_count() -> usize!:
        try self.ensure_open()
        return self.raster.channels.length

    pub func channel_name(index: usize) -> str!:
        try self.ensure_open()
        if index >= self.raster.channels.length:
            error(invalid, "channel index out of range")
        return self.raster.channels[index].name

    pub func channel_type(index: usize) -> SampleType!:
        try self.ensure_open()
        if index >= self.raster.channels.length:
            error(invalid, "channel index out of range")
        return self.raster.channels[index].kind

    ## The index of the channel named `name`; an error when there is none.
    pub func channel_index(name: str) -> usize!:
        try self.ensure_open()
        return try self.raster.find_channel(name)

    ## The Pillow mode the channels make, or "MULTI" when they fit none (named
    ## AOV channels, mixed sample types).
    pub func mode() -> str!:
        try self.ensure_open()
        let channels = self.raster.channels
        let kind = channels[0].kind
        for channel in channels:
            if channel.kind != kind:
                return "MULTI"
        if channels.length == 1:
            return "L" if kind == .uint8 else "I;16" if kind == .uint16 else "I" if kind == .uint32 else "F"
        if channels.length == 2 and channels[0].name == "Y" and kind == .uint8:
            return "LA"
        if channels.length == 3 and channels[0].name == "R" and channels[1].name == "G" and channels[2].name == "B":
            return "RGB" if kind == .uint8 else "RGBF" if kind == .float32 else "MULTI"
        if channels.length == 4 and channels[0].name == "R" and channels[3].name == "A":
            return "RGBA" if kind == .uint8 else "RGBAF" if kind == .float32 else "MULTI"
        return "MULTI"

    ## Whether the file is a camera raw luce-raw develops (so its pixels can come
    ## straight from `raw.develop`, a tile at a time).
    pub func is_camera_raw() -> bool:
        return not self.closed and is_raw_format(self.raster.file_format)

    ## The file's bytes as read, for decoders working from them directly (a
    ## camera raw's; only a PNG or JPEG is opened from its start alone).
    pub func encoded_bytes() -> const u8[]:
        return self.raster.encoded

    ## How many threads decoding uses.
    pub func thread_count() -> usize:
        return self.threads

    ## Whether the pixels are decoded; most reads decode them on first use.
    pub func is_loaded() -> bool:
        return not self.closed and self.raster.pixels.length > 0

    ## How many threads the last decode used.
    pub func workers_used() -> usize:
        return self.active_workers

    ## Decode the pixels now, in parallel for TIFF, EXR, HEIC and camera raws.
    pub func load() -> !:
        try self.ensure_open()
        if self.is_loaded():
            return
        try self.read_whole_file()
        try self.raster.allocate()
        errdefer self.discard_pixels()
        if self.raster.file_format == "PNG":
            try png.decode(&self.raster)
            self.active_workers = 1
        elif self.raster.file_format == "JPEG":
            try jpeg.decode(&self.raster)
            self.active_workers = 1
        elif self.raster.file_format == "HEIC":
            try heic.decode(&self.raster, self.threads)
            self.active_workers = self.threads
        elif is_raw_format(self.raster.file_format):
            # A raw develops whole, on its own threads.
            try raw.decode(&self.raster, raw.Options(threads = self.threads))
            self.active_workers = self.threads
        elif self.raster.file_format == "TIFF":
            self.active_workers = try parallel.decode(&self.raster, tiff.decode_chunk, self.threads)
        else:
            self.active_workers = try parallel.decode(&self.raster, exr.decode_chunk, self.threads)

    ## A picture opened from its file's start alone gets the file whole, for a
    ## decode that works from it all. The file must not have changed.
    func read_whole_file() -> !:
        if not self.head_only:
            return
        let whole = try read_whole((c_api.str)self.raster.path, self.raster.max_bytes)
        errdefer free(whole) in memory.heap
        if (u64)whole.length != self.file_size:
            error(invalid, "the picture's file changed since it was opened")
        if self.raster.file_format == "PNG":
            # The probe's palette and transparency, of the whole file now; the
            # scratch raster only borrows the bytes.
            var scratch = model.Raster(max_bytes = self.raster.max_bytes, max_pixels = self.raster.max_pixels)
            scratch.encoded = whole
            defer:
                var empty: u8[]
                scratch.encoded = empty
                scratch.close()
            try png.probe(&scratch)
            self.raster.palette = scratch.palette
            self.raster.transparency = scratch.transparency
        free(self.raster.encoded) in memory.heap
        self.raster.encoded = whole
        self.head_only = false

    func discard_pixels():
        if self.raster.pixels.length > 0:
            free(self.raster.pixels) in memory.heap
        var empty: f64[]
        self.raster.pixels = empty
        self.active_workers = 0

    ## Select frame `frame` of the file, as Pillow's seek; the pixels decode again on use.
    pub func seek(frame: usize) -> !:
        try self.ensure_open()
        if frame == self.raster.frame:
            return
        try self.read_whole_file()
        let selected = try Image.open_bytes(self.raster.encoded, self.threads, frame, self.raster.max_bytes, self.raster.max_pixels)
        defer selected.release()
        let other = selected.value()
        if self.raster.path.length > 0:
            with memory.heap:
                other.raster.path = try strings.copy(self.raster.path)
        self.raster.close()
        self.raster = other.raster
        other.raster = model.Raster()
        self.active_workers = 0

    func offset(x: usize, y: usize, channel: usize) -> usize!:
        if x >= self.raster.width or y >= self.raster.height or channel >= self.raster.channels.length:
            error(invalid, "pixel or channel index out of range")
        return (y * self.raster.width + x) * self.raster.channels.length + channel

    ## One raw sample of one channel, in the channel's own range.
    pub func get_sample(x: usize, y: usize, channel: usize = 0) -> f64!:
        try self.load()
        return self.raster.pixels[try self.offset(x, y, channel)]

    ## Set one raw sample of one channel.
    pub func put_sample(x: usize, y: usize, channel: usize, value: f64) -> !:
        try self.load()
        self.raster.pixels[try self.offset(x, y, channel)] = value

    ## The color at a pixel from its Y or R, G, B and A channels, in the samples'
    ## own range; alpha is the maximum when there is no A channel.
    pub func getpixel(x: usize, y: usize) -> Pixel!:
        try self.load()
        _ = try self.offset(x, y, 0)
        var r: f64 = 0.0
        var g: f64 = 0.0
        var b: f64 = 0.0
        var a = model.maximum(self.raster.channels[0].kind)
        for c in 0..<self.raster.channels.length:
            let name = self.raster.channels[c].name
            let value = self.raster.pixels[(y * self.raster.width + x) * self.raster.channels.length + c]
            if name == "Y":
                r = value
                g = value
                b = value
            elif name == "R":
                r = value
            elif name == "G":
                g = value
            elif name == "B":
                b = value
            elif name == "A":
                a = value
        return Pixel(r, g, b, a)

    ## Set a pixel's color channels; named non-color channels take `put_sample`.
    pub func putpixel(x: usize, y: usize, pixel: Pixel) -> !:
        try self.load()
        _ = try self.offset(x, y, 0)
        for c in 0..<self.raster.channels.length:
            let name = self.raster.channels[c].name
            if name != "Y" and name != "R" and name != "G" and name != "B" and name != "A":
                error(invalid, "use put_sample for named non-color channels")
        for c in 0..<self.raster.channels.length:
            let name = self.raster.channels[c].name
            self.raster.pixels[(y * self.raster.width + x) * self.raster.channels.length + c] = pixel.a if name == "A" else pixel.g if name == "G" else pixel.b if name == "B" else pixel.r

    pub func metadata_count() -> usize!:
        try self.ensure_open()
        return self.raster.attributes.length

    pub func metadata_key(index: usize) -> str!:
        try self.ensure_open()
        if index >= self.raster.attributes.length:
            error(invalid, "metadata index out of range")
        return self.raster.attributes[index].name

    ## A string attribute's value, or empty when there is none; typed ones take `metadata_bytes`.
    pub func metadata(name: str) -> str!:
        try self.ensure_open()
        for entry in self.raster.attributes:
            if entry.name == name:
                if entry.type_name != "string":
                    error(invalid, "typed metadata must be read with metadata_bytes")
                return (str)entry.data
        return ""

    ## An attribute's type name as the file stores it ("string", EXR's "v2f"…), or empty.
    pub func metadata_type(name: str) -> str!:
        try self.ensure_open()
        for entry in self.raster.attributes:
            if entry.name == name:
                return entry.type_name
        return ""

    ## An attribute's raw bytes, whatever its type, or empty.
    pub func metadata_bytes(name: str) -> const u8[]!:
        try self.ensure_open()
        for entry in self.raster.attributes:
            if entry.name == name:
                return entry.data
        return b""

    ## Move the data window's top-left, as EXR stores it.
    pub func set_origin(x: i64, y: i64) -> !:
        try self.ensure_open()
        if x < -2147483648 or y < -2147483648 or x > 2147483647 - (i64)self.raster.width + 1 or y > 2147483647 - (i64)self.raster.height + 1:
            error(invalid, "image data window exceeds int32")
        self.raster.xmin = x
        self.raster.ymin = y

    ## The path the image was opened from, or empty.
    pub func source_path() -> str!:
        try self.ensure_open()
        return self.raster.path

    pub func set_metadata(name: str, value: str) -> !:
        try self.ensure_open()
        if strings.contains(name, "\0"):
            error(invalid, "metadata name contains NUL")
        try self.raster.attribute(name, "string", value.bytes)

    ## Encode and write atomically to `path`: the format from `file_format` or the
    ## extension; `compression` and `tile` for TIFF and EXR, `quality` (1..100) for
    ## JPEG, `bigtiff` for TIFF.
    pub func save(path: str, file_format: str = "", compression: str = "zip", quality: i64 = 90, tile: usize = 0, bigtiff: bool = false) -> !:
        try check_path(path)
        # Managed Luce text is a byte view, not necessarily NUL-terminated.
        let destination = try strings.copy(path)
        defer strings.release(destination)
        var selected = file_format
        if selected.length == 0:
            let dot = strings.find_last(path, ".") else error(invalid, "output format is required without a filename extension")
            selected = (str)path.bytes[dot + 1..]
        let encoded = try self.encode(selected, compression, quality, tile, bigtiff)
        defer free(encoded) in memory.heap
        try files.write_atomic((c_api.str)destination, encoded)

    ## The image encoded as `file_format` ("png", "jpg"/"jpeg", "tif"/"tiff" or
    ## "exr"), with the options `save` takes: heap bytes the caller frees.
    pub func encode(file_format: str, compression: str = "zip", quality: i64 = 90, tile: usize = 0, bigtiff: bool = false) -> u8[]!:
        try self.load()
        let lower = try strings.to_lower(file_format)
        defer strings.release(lower)
        var encoded = Buffer(maximum = self.raster.max_bytes)
        defer encoded.close()
        if lower == "png":
            if tile != 0 or bigtiff:
                error(invalid, "tile and BigTIFF options do not apply to PNG")
            try png.encode(&self.raster, &encoded)
        elif lower == "jpg" or lower == "jpeg":
            if tile != 0 or bigtiff:
                error(invalid, "tile and BigTIFF options do not apply to JPEG")
            try jpeg.encode(&self.raster, &encoded, quality)
        elif lower == "tif" or lower == "tiff":
            try tiff.encode(&self.raster, &encoded, compression, tile, bigtiff)
        elif lower == "exr":
            if bigtiff:
                error(invalid, "BigTIFF option does not apply to EXR")
            try exr.encode(&self.raster, &encoded, compression, tile)
        else:
            error(unsupported, "unsupported output image format")
        let view = encoded.view()
        let bytes = try new u8[view.length] --- in memory.heap
        memory.copy(bytes, view, view.length)
        return bytes

    pub func close():
        if self.closed:
            return
        self.raster.close()
        self.closed = true

pub let image_type: interop.Type[Image] = interop.Type[Image]("Image", Image.close, closeable = true)

## The most a picture decoded whole may take as f64 samples.
pub let whole_picture_bytes: usize = 4294967296

## A file's bytes, heap storage of exactly its size (at most `most`): read
## into one buffer rather than one grown by doubling, which for a picture of
## hundreds of megabytes left as much again behind.
func read_whole(path: c_api.str, most: usize) -> u8[]!:
    var file = try files.File.open(path)
    defer file.destroy()
    let size = try file.seek(0, files.SeekOrigin.end)
    _ = try file.seek(0)
    if size < 0 or (u64)size > (u64)most:
        error(limit, "the file exceeds the read limit")
    let data = try new u8[(usize)size] --- in memory.heap
    errdefer free(data) in memory.heap
    var used: usize = 0
    while used < data.length:
        let count = try file.read(data[used..])
        if count == 0:
            error(invalid, "the file ended before its size")
        used += count
    return data