Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

The layered-document engine behind luced-2d: layers, GPU compositing, selections, painting, filters, transforms and history over shared GPU tiles, with a Pillow-inspired Image API and Cryptomatte 1.2.

A library written in luce-base. Latest release 0.45.1.

Install#

luc add dymokomi/luce-image

Documentation#

luce-image

The layered-document engine behind luced-2d, and the Pillow-inspired owning Image API it opens pictures through, implemented in Luce Base.

Every file format is its own package. luce-image's Image opens and saves through luce-png, luce-jpeg, luce-tiff and luce-exr (and reads Photoshop documents through luce-psd), which share luce-raster (the pixel model, byte readers and error codes) and luce-compress; each depends only on the standard library and those two. luce-image adds the owning Image API, threaded decoding and the layered-document engine. The brush engine is luce-painting, vector layers are luce-vector, Cryptomatte is luce-exr's and SVG rendering luce-svg's.

All runtime codec internals are Luce Base. There are no libjpeg, libpng, libtiff, OpenEXR, zlib or Python bindings in the library. The Base standard library supplies memory, file I/O, math and threads. Independent established codecs are used only by the test suite.

Status: experimental. The supported profiles below are implemented, not native fallbacks. This is not yet a complete replacement for every TIFF/OpenEXR profile; unsupported encodings return errors. See format coverage.

Use from Luce

Depend on it from the application's package.prisma:

def dependency "luce-image" {
    str owner = "dymokomi"
    str version = "^0.41.0"
}

Its public imports are image (the Image API), canvas (the layered-document engine) and brush_files (brush masks from pictures and files, kept as PNG).

from luce_image.image import Image

pub func main(arguments: list[str]) -> int!:
    let image = Image.open(arguments[0], threads = 4)
    print(image.size())
    let preview = image.convert("RGB").resize(512, 512, resample = "bilinear")
    preview.save(arguments[1])
    return 0

open snapshots encoded bytes and reads the header; pixels decode lazily on load, pixel access, transformation or save. TIFF strips/tiles and EXR chunks decode on luce-canvas's worker pool, at most threads at once. JPEG/PNG decoding and all encoding are currently single-threaded. workers_used() reports how many threads the chunks were spread over.

The managed Luce handle owns the Base image. close() is idempotent and closes all aliases; use copy() for independent pixels. No manual freeing is needed in Luce. Native Base consumers release their interop.Reference.

Layered documents: Canvas

The editor engine behind luced-2d, all Luce Base on the GPU (std.gpu), with a Luce-facing Canvas object:

  • A layer tree of 256×256 rgba16 tiles in linear light, straight alpha; the 26 Photoshop blend modes, opacity, visibility, layer masks and clipping masks, composited per tile through one shader with a cache keyed on what each tile depends on, and a pyramid for zoomed-out views. Colors mix as their sRGB-encoded values wherever they mix, as Photoshop's do, unless the document blends with gamma 1.0 (set_linear_blend; see how colors blend).
  • Per-pixel selections (rectangle, ellipse, polygon/lasso, magic wand; add, subtract, intersect, invert, expand, contract, feather) that painting, fills and crops respect, drawn as marching ants.
  • GPU brush and eraser strokes as spaced dabs with Photoshop's controls — tip angle and roundness, spacing, smoothing, size/angle/roundness/flow/color jitter, scattering, and dynamics that drive size, flow, opacity, angle, roundness, scatter, texture depth and color jitter from the pen's pressure, tilt, azimuth, barrel rotation and airbrush wheel, the stroke's direction and velocity, or a fade, each with a minimum and a response curve (set_brush_dynamics, set_brush_dynamic, strokes taking the pen per point); sampled grayscale tips up to 1024 px and texture images tiled in document space, built-in or the brush's own, multiplied or subtracted per dab on the GPU (set_brush_tip, set_brush_texture_image, set_brush_texture); luce-painting's BrushMask to paint, invert and preview tips and textures, opened and kept as PNG through brush_files, and selection_image for Define Brush Preset; destructive adjustments (brightness/contrast, hue/saturation/lightness, invert, levels, curves, desaturate, threshold, posterize), Gaussian blur, free transform, move, canvas and image resize, text from std.fonts; each undoable, and each previewable live on the layer's original pixels before it is kept.
  • Layer styles — drop shadow, outer glow, stroke — rendered under the layer by the compositor, non-destructively.
  • Documents open from any picture, from .l2d documents (one file of the layers' half-float tiles, a manifest and a preview; see the .l2d format) and from Photoshop .psd files (through the luce-psd package); they save as .l2d or flatten to a picture.

Build and test

python3 -m venv build/test-env                  # the oracles: Pillow, tifffile, imagecodecs, OpenEXR
build/test-env/bin/python -m pip install -r tests/requirements.txt
luc test

luc test runs the module tests and tests/oracles, which skips when the oracles are not installed. See testing for dependencies and CI.

The GPU shaders are GLSL under src/shaders/; after changing one, regenerate src/shaders.lucb with luce-gpu's generator (needs glslangValidator and spirv-cross): python3 ../luce-gpu/tools/embed_shaders.py --public -I ../luce-color/shaders src/shaders.lucb src/shaders/composite.frag src/shaders/adjust.frag src/shaders/blur.frag src/shaders/ants.frag src/shaders/warp.frag src/shaders/spread.frag src/shaders/style.frag src/shaders/lift.frag src/shaders/mask_mix.frag src/shaders/adjust_mix.frag src/shaders/resample.frag src/shaders/float.frag src/shaders/encode.frag src/shaders/liquify.frag src/shaders/quickmask.frag src/shaders/mesh.frag src/shaders/channels.frag src/shaders/transfer.frag (this order keeps the generated file stable). srgb.glsl, the sRGB curve the shaders mix through, is luce-color's.

Documentation: API, formats, design and limits, how colors blend, upstream attribution. Measured thread scaling records the initial benchmark. Validation results distinguish local checks from CI.

MIT licensed; see LICENSE.

Dependencies#

Versions#

0.45.1

Browse source · pack · commit ce23b83349a8

SHA-256 a7ba9df2c42afe5b025f9e4d24952a0d5b599ba4be2926f7737a8983b94e10c9

luce-image 0.45.1: batch release

0.45.0

Browse source · pack · commit c9f00ed00f65

SHA-256 254a1ef10fec7b8fd4fc704b204598e322b8579a92fc17008b95bb197af5ab68

byte spans compare with ==; dependencies name no version