Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-develop

Photo development for Luce: camera RAWs and JPEG/PNG/TIFF/HEIC sources, quick oriented previews, and a scene-linear develop pipeline with a GPU renderer for viewers and a CPU path for export.

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

Install#

luc add dymokomi/luce-develop

Documentation#

luce-develop

Photo development for Luce, written in Luce Base. It reads camera raws (through luce-raw) and JPEG, PNG, TIFF and HEIC files, makes quick upright previews for libraries and viewers, and will develop photos through a scene-linear pipeline: white balance, exposure, tone, Oklab color tools and the ACES 2.0 view transform. A GPU renderer serves viewers and a CPU path serves export. luced-photo is its first user; the design is in luced-photo's docs/DESIGN.md.

Sources (source)

  • kind(data) -> Kind: raw, jpeg, png, tiff, heic or unknown, by the bytes.
  • is_photo_name(name): whether an importer should look at a file, by its extension.
  • preview(data, long_edge, orientation = 0) -> Picture: a display-ready preview, upright, at most long_edge on its longer side. For a raw it is the largest embedded JPEG. When a raw has none, or only a thumbnail much smaller than asked for (Leica's DNGs carry 160 px), it is a half-size develop instead. A JPEG decodes at 1/2 to 1/8 size from its DCT. PNG, TIFF and HEIC decode whole. orientation 0 uses what the file states where luce-develop reads it.

Pictures (picture)

Picture is 8-bit RGBA (sRGB, straight alpha). shrunk(long_edge) averages in linear light, oriented(exif) turns it upright, and save_jpeg(path, quality) writes it out. width(), height() and pixels() read it from Luce.

Developing (settings, scene, renderer, process, view)

Before anything else, the output position is mapped onto the photo by the geometry (geometry). That covers perspective as the camera turned back (roll, tilt, pan through a 28 mm-equivalent lens), aspect, scale, and crop to fit. Guides drawn on the photo that should be vertical or horizontal solve for the turn (Nelder–Mead, after darktable's ashift). geometry.frame_map is the one matrix the shader and the CPU path both sample through.

The develop works in scene-linear ACES AP1. A raw is developed once by luce-raw with camera set (balanced as shot, no matrix). A new white balance is then just a matrix built from luce-raw's rendering. The stages, in the order the shader (shaders/develop.frag) and the CPU path (process) run them:

  1. The matrix: white balance, camera color and exposure.
  2. Lens vignetting correction.
  3. Film, when a stock is chosen: the scene exposed onto a color negative, developed, and scanned back to AP1 (film, below).
  4. Tone: contrast, highlights, shadows, whites and blacks as one gain over luminance, so hues hold (tone).
  5. In Oklab: vibrance and saturation; the Color Mixer (eight hue bands' hue, saturation and luminance); Color Grading (shadows, midtones, highlights and global wheels, balance, blending); Black & White (hue weights, tint).
  6. The view: ACES 2.0 SDR (luce-color), lifted one stop so photographs land as a camera renders them, which is the default; Standard, a neutral filmic curve; Linear; or Print, the scene printed on Kodak Vision 2383 and projected (film_print, below).
  7. Levels and Curves (all channels, R, G, B, luma) on the display's encoded values.
  8. The vignette.
  • Parameters. All 85 are in tools/parameters.py, which generates src/parameters.lucb: each one's name, label, Properties section, range, default and decimals.
  • Tables. Everything per hue, per tone or per curve is built into one 1024×4 table (tables), which both paths read with the same filtering.
  • Settings for Base. settings.Settings holds the values and five curves. parse(text) and text_of read and write the short text form that catalogs store ("exposure=0.7;curve_rgb=0,0 0.3,0.25 1,1").
  • Looks for Luce. settings.look(text) returns a Look with get/set(name), set_curve, text() and load(text). name_of(i), label_of(i), section_of(i) and the rest describe the table, so an application can build its controls from it.
  • Scenes. scene.open(path, edge) loads a photo at a viewer's size.
  • The renderer (GPU, for viewers).

    • open(path, edge) loads on the renderer's own thread, and poll() takes in what loaded.
    • set_settings(settings) changes the develop.
    • draw(target, x, y, w, h) draws every frame, as one pass.
  • The CPU path. process.render(scene, settings) and render16 are the same develop on the CPU, rows spread over every processor, with the view evaluated exactly.
  • Export. export.export(source, settings, target, format, quality, edge, space) develops at full size (or a long edge) for sRGB or Display P3 (space; the view renders for that display's primaries) and writes JPEG or 16-bit PNG with the matching ICC profile (luce-color's icc.write_named_profile): about 2 s for a 24 MP raw, demosaic included. scene.open(path, 0) is a full-size scene.
  • Parity. tests/parity/main.lucb holds the GPU to the CPU for every tool. Both paths agree to within a level on average, and to 3 levels for Standard and Linear.

Recipes (recipe)

A photo's settings carry its recipe, the film process it goes through: the File, the camera (White Balance, Exposure, Lens, Filter), the Film and its Development, then an output: a Telecine (Scan, Grade, View), a Release Print (Print, Project), a Lightbox, a Paper Print or a Digital Intermediate (Scan, Grade, Record, Print, Project); the Easel frames it. White Balance, Lens and Filter are each there or not; the rest follows from the output. Each stage owns parameter sections (owner_of). settings.compile(settings) is what renders: the sections of stages not in the recipe at their defaults, and the view as the output has it (the 2383 print view for a projected print, the paper view for paper). The renderer, process and export compile on entry. Recipes are stored as recipe=telecine|white_balance in the settings text, omitted for the default (Television's). Look reads and sets them (has_stage, output, set_output, set_stage_used), and mode_text(at) gives a mode (Television, Cinema, Slide, Black & White and others) as settings to stack on a photo.

Film (film)

The Film section turns the develop into a color negative and its transfer, the way television shot on film reached the screen: Kodak negative, developed, scanned on a telecine and graded on tape. Film works on the negative, at the scene's own size (no finer than its scan's Resolution) and before the develop, so the tone and color tools grade the scan and the view stays the only tone scale. Everything comes from the stock's datasheet (film_stocks.lucb, modelled by film_model.lucb):

  1. Exposure. What the camera recorded becomes what each layer would have received (film_exposure.lucb): a third-order root-polynomial from the camera's values to the layers' exposures, fitted on 190 real surfaces and blue sky under the light on set, through the camera's spectral sensitivities (luce-color's camera: measured, or estimated from the raw's color matrix) and the layers'. Other pictures come as XYZ, the CIE observer their camera. Each layer is relative to the stock's balance light (3200 K for tungsten stocks). Middle grey lands on the stock's normal exposure; Exposure over- or underexposes the negative, which the scan does not take back. Filter decides the light: Matched (the default) balances it to the stock, as a white balance does; with None or 85, the White Balance's Temperature and Tint become the light on set (as shot unless set), so daylight on tungsten film goes blue unless an 85 warms it (and takes its 2/3 of a stop). Color Filter puts a black-and-white photographer's filter on the lens (Yellow 8, Orange 21, Red 25, Green 11, Blue 47, modelled on Wratten curves): its transmission multiplies the light before the layers see it, and exposure opens up by its factor. Development (film_develop.lucb) follows the stock's process (ECN-2 3:00 at 41.1 °C, E-6 first developer 6:00 at 37.8 °C, D-76 7:00 at 20 °C for Acros); Time and Temperature push or pull it. A negative gains contrast and speed as Acros II's D-76 curves at 4, 7 and 10 minutes do; a slide rates faster, a stop for each published E-6 push step. The scan stays set for a normal negative, so a push shows its density, contrast and grain.
  2. Light in the emulsion. Each layer's exposure scatters (an exponential, the emulsion's classic spread of light); Halation adds light that came back off the base, mostly to the red layer, weak behind rem-jet backing.
  3. Development. The characteristic curves (Status M) are unmixed into cyan, magenta and yellow dye amounts. Developing releases inhibitor (DIR couplers) that diffuses and holds development back nearby: in the layer itself, which develops edges harder, and in its neighbours, which saturates colors and shifts hues (Interimage). The curves are corrected so neutrals keep the datasheet's densities. Each layer's scatter and self-inhibition and the inhibitor's spread are fitted to the stock's MTF curves, within about 20% everywhere (film_model.lucb).
  4. Grain. The developed negative is made of dye clouds (each stock's own: soft and about 8 µm apart on Kodak's negatives, finer on Velvia, small and crisp-edged on Acros II, whose Super Fine-Σ grains are known for it): each takes the film's density at its own place plus its grain (how many of its silver grains developed, which varies as the stock's rms granularity says it does at that density), and every point is the clouds around it blended. Nothing finer than the clouds survives, and the grain follows the image. Calibrated so a 48 µm aperture over an even patch reads Kodak's number; Format sets how much negative a pixel covers.
  5. Scan. The dyes' spectral density over D-min (the orange mask removed), inverted per channel at grey, the clear negative's floor taken out by Black, a matrix fitted per stock back to AP1, then the telecine's Warmth, Tint and Contrast.

The passes on the negative (film_passes.lucb on the CPU, film_gpu.lucb and shaders/film.frag on the GPU) are: expose, scatter (across, down), halation (across, down), the neutral development, the inhibitor's spread (across, down), and develop as dye clouds with their grain, and scan. The renderer runs them when the photo or the settings change and draws the filmed scene; export runs them at full size (about 18 s for a 48-megapixel raw on the CPU, demosaic included).

Print (film_print, the View's Kodak 2383 Print) is the cinema's release print, the other half of the film process, as a view: it replaces the tone scale rather than stacking on one. The graded scene is held as a negative's printing density the Cineon way (0.6 density per decade, grey at 0.70), printer lights put grey on the visual neutral Kodak's dyes are normalized to, each layer develops through 2383's characteristic curve (Status A, unmixed into dye amounts), and the dyes are projected under a xenon arc with a little flare, the eye adapted to the screen. Kodak's 2383 sheet has raster graphs: dev/film/trace_raster_curves.py follows each curve column by column; release print curves are made to one shape, so the three are read as that shape set apart, which Kodak's toes (run together on the graph) cannot be read apart for.

Stocks, 22 of them, each from its maker's sheet:

  • Television's 1990s tungsten negatives: Kodak EXR 500T 5298 and EXR 200T 5293, Vision 500T 5279 and Vision 320T 5277.
  • Cinema today: Vision3 500T 5219, 200T 5213, 250D 5207 and 50D 5203.
  • CineStill: 800T and 50D, Vision3 5219 and 5203 with the rem-jet taken off, developed in C-41 and rated as sold. Nothing stops the light the base sends back, so highlights get CineStill's red-orange halo.
  • Still color negatives (C-41): Portra 160, 400 and 800, Ektar 100, Fujifilm Pro 400H.
  • Slides (E-6): Fujifilm Velvia 50 and 100, Kodak Ektachrome E100.
  • Black and white: Fujifilm Neopan 100 Acros II, Kodak Tri-X 400 and T-MAX 100, Eastman Double-X 5222, Ilford HP5 Plus.
  • The 1960s: Eastman Color Negative 5251, 2001: A Space Odyssey's 65 mm negative, from Kodak's 1968 paper on 5254 (same sensitivities and dyes).

A slide's dyes form a positive, seen on a D50 lightbox and brought into scene light through the ACES view's inverse, as display pictures come in; the model balances its layers so grey looks grey there (sheets' typical curves stand a few hundredths apart). A black-and-white film is three identical layers of its sensitivity, neutral silver, one grain for all three channels, developed per its sheet's normal curve in its own process and time (Tri-X: D-76, 8 minutes; HP5: Ilfotec HC, Ilford's HC-110 dilution B).

Most sheets' graphs are vector paths, read exactly by read_drawings.py (curves by drawing index, axes from the tick labels, an overlay image of every graph to check against), with each stock's spec in sheets_*.py; older or Fujifilm and Ilford sheets are raster scans, traced by trace_raster_curves.py. Kodak's and Fujifilm's still sheets draw the midscale neutral, not each dye, so those stocks take Vision3 250D's dye shapes; sheets that print a grain index rather than an rms granularity, and those without an MTF, have estimates, said so in each stock's source line. dev/film holds the readings, the scripts that took them, and make_stocks.py, which writes film_stocks.lucb. Kodak publishes nothing above log H 0, no interimage numbers and no Status M tables: the shoulder, the interimage matrix and the densitometer's bands (Gaussians at Status M's band centres) are estimates, labelled where they are made. The model builds in about 0.2 s when a stock is first chosen; after that a settings change only recomputes the development and the timing.

Looks (looks)

Looks are the film process of particular pictures, as their makers documented it (American Cinematographer, Kodak, the labs): a mode and the settings that make it that picture. Munich, Saving Private Ryan, Se7en, Fight Club, The Godfather, Barry Lyndon, Days of Heaven, Lawrence of Arabia, 2001, Three Kings, Nineteen Eighty-Four, O Brother, Where Art Thou?, Moonrise Kingdom, The French Dispatch and Oppenheimer, besides Friends. They use what the engine models for them: silver kept on the negative or on the print (as the labs set ENR and CCE, by infrared density: 0.60 a normal print, 2.40 none bleached), flashing, push and pull, the 85, 81 and Coral filters, Eastman Color Negative 5254 (5251 a stop faster, as Kodak's 1968 paper describes it), and stand-ins where a stock is not here, each named in looks.lucb. Dye-transfer prints, Low Contrast filters, uncoated lenses and intermediate generations are not modelled yet.

Stages beyond the negative

  • Lens (lens): veiling glare beyond a modern lens's, for single-coated and uncoated lenses and Tiffen Low Contrast filters (estimates).
  • Filters: 85, 81A, 81EF, ½ Coral; black-and-white Wratten filters; Chocolate 1–3 (Lee 156's spectrum at a share of its density, an estimate).
  • Record: the digital intermediate's film recorder, so a graded scan prints.
  • Print (film_print): Vision 2383 or Technicolor dye transfer (dyes from Flueckiger et al.'s 2018 measurement of a 1949 print, tone estimated), printer lights, silver kept (ENR, CCE, by infrared density), duplication generations and an optical step (blur from the 2004 SMPTE resolution study, grain in quadrature).
  • Paper (film_paper): six photographic papers from their sheets, by grade or CC filtration, contact or enlarged (the Callier effect, enlarger flare), seen by reflection under D50.
  • Formats: 35 mm Academy, Super 35, 16 mm, Super 16, 65 mm, IMAX 15/70.

Tests

luc test runs the module tests and the test programs in tests/<name>/. One of those is tests/parity, which holds the GPU to the CPU on a Leica DNG, a Fuji X-Trans RAF and a Sony ARW from ../luce-raw/build/samples. It is skipped when those samples or a GPU are not there; luce-raw's tests fetch the samples.

Dependencies#

Versions#

0.1.0

Browse source · pack · commit a7276fd348d8

SHA-256 e63e3fd720d3923a69f7df5aa6e64e69ecfd0aea7829c87bc45e9244b6593e2d

luce-develop 0.1.0: first release