Filmtone's two-lane LUT pipeline implementation — the inputLut/creativeLut data model and intensity blending via CIColorMatrix

Splitting Source Profile and Look into two slots

Filmtone holds `.cube` LUTs in two slots. `inputLut` is source-specific: camera transforms, Apple Log to Rec.709, anything tied to the material. `creativeLut` is look-specific: the creative / stylistic LUT layered on top of a Filmtone preset. With one slot, swapping cameras either wipes the look or forces you to give up the camera transform to keep the look. Two slots let both responsibilities coexist.

Data model

// apps/capacitor-film-lab-ios/ios/App/App/FilmtoneMediaTypes.swift
struct ParsedCubeLutDTO: Codable {
    let title: String
    let size: Int
    let data: [Double]
    let intensity: Double
}

struct SerializableLutDTO: Codable {
    let size: Int
    let data: [Double]
    let intensity: Double
}

struct Phase0ExportRequestDTO: Codable {
    let sourceUri: String
    // ...
    let lut: ParsedCubeLutDTO?           // legacy, decode-only
    let inputLut: SerializableLutDTO?    // Source Profile / Camera
    let creativeLut: SerializableLutDTO? // Look
    // ...
}

The legacy `lut` field stays for decode compatibility only. Current export-request builds set `lut: nil` and transport `inputLut` and `creativeLut` independently. `FilmtonePhase0Math.buildExportRequest` enforces this, and `verify:swift-contract`'s Phase0 fixtures verify it on every gate.

Export order is fixed

1. input LUT — Source Profile / Camera transform
2. base grade — the Filmtone preset core (params)
3. tone compression
4. edge optics — lens softness, RGB shift
5. glow family — bloom, halation, diffusion
6. vignette
7. grain
8. creative LUT — the look's final pass
9. print — the last touch of paper-print character

Input lands first (the source enters Filmtone's working space) and creative lands last (the look sits on top as the final layer). The ordering is fixed and the same in preview and export; `verify:swift-contract` keeps them in lockstep.

Replacement preserves look, not source profile

When the source is replaced (a different video, a different camera), `inputLut` is dropped — the new material likely needs a different transform. `creativeLut` is preserved because look should be independent of material. `clearInputLut()` and `clearCreativeLut()` are completely independent APIs; neither pulls the other along.

// apps/capacitor-film-lab-ios/ios/App/App/FilmtoneEditorStore.swift
func clearInputLut() {
    applyLutMutation { $0.inputLut = nil }
}

func clearCreativeLut() {
    applyLutMutation { $0.creativeLut = nil }
}

Funneling all LUT mutation through one helper

Every LUT change goes through `applyLutMutation`. It updates `updatedAt`, invalidates the rendered output state (preview task, compare frame, export result, export progress) in one shot, persists, and reschedules a preview render. Setters (`setInputLutIntensity`, `setCreativeLutIntensity`) call the same helper, so callers don't have to track the side-effect cascade themselves.

private func applyLutMutation(_ mutate: (inout FilmtoneProjectState) -> Void) {
    mutate(&project)
    project.updatedAt = FilmtonePhase0Math.isoTimestamp()
    invalidateRenderedOutputState()
    persist()
    schedulePreviewRender()
}

func setInputLutIntensity(_ intensity: Double) {
    let clamped = FilmtonePhase0Math.clampLutIntensity(intensity)
    guard let current = project.inputLut, current.intensity != clamped else { return }
    applyLutMutation {
        guard let lut = $0.inputLut else { return }
        $0.inputLut = lut.withIntensity(clamped)
    }
}

Linear intensity blending in Core Image

`FilmtoneExportSession.applyLut` returns the LUT result directly when `PreparedLut.intensity >= 0.999`. Below that, it scales alpha to `intensity` via `CIColorMatrix`, then composites the alpha-scaled LUT image over the source via `CISourceOverCompositing`. The result is `lut * intensity + original * (1 - intensity)`. The `>= 0.999` early return keeps the common 100% path off the compositing cost.

// apps/capacitor-film-lab-ios/ios/App/App/FilmtoneExportSession.swift
private func applyLut(_ lut: PreparedLut, to image: CIImage) -> CIImage {
    let lutImage = image.applyingFilter("CIColorCubeWithColorSpace", parameters: [
        "inputCubeDimension": lut.size,
        "inputCubeData": lut.cubeData,
        "inputColorSpace": outputColorSpace,
    ])

    guard lut.intensity < 0.999 else { return lutImage }

    let alphaAdjusted = lutImage.applyingFilter("CIColorMatrix", parameters: [
        "inputAVector": CIVector(x: 0, y: 0, z: 0, w: lut.intensity),
    ])
    return alphaAdjusted
        .applyingFilter("CISourceOverCompositing", parameters: [
            kCIInputBackgroundImageKey: image,
        ])
        .cropped(to: image.extent)
}

How intensity travels from UI to rendering

SwiftUI Slider → `setInputLutIntensity(value)` → `clampLutIntensity(0...1)` → `ParsedCubeLutDTO.withIntensity(clamped)` → `applyLutMutation` → `schedulePreviewRender` → preview rebuild. Export request reads the same project state, and `makePreparedLut(from: SerializableLutDTO?)` carries `PreparedLut.intensity` straight into `applyLut`. Nobody can override intensity midstream — there's no second source of truth.