luvix 0.1.1__py3-none-any.whl

luvix/__init__.py

@@ -0,0 +1,8 @@
+"""Luvix HDR image processing toolkit."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("luvix")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

luvix/__main__.py

@@ -0,0 +1,6 @@
+"""Run Luvix with ``python -m luvix``."""
+
+from luvix.cli import app
+
+if __name__ == "__main__":
+    app()

luvix/backends/apple/bridge.py

@@ -0,0 +1,43 @@
+"""Compile and execute the macOS ImageIO backend on demand."""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import subprocess
+from importlib.resources import files
+from pathlib import Path
+
+
+class BackendError(RuntimeError):
+    """Native backend failed."""
+
+
+def backend_binary() -> Path:
+    if platform.system() != "Darwin":
+        raise BackendError("Apple HDR backend requires macOS; no portable backend yet")
+    source = Path(str(files("luvix.backends.apple").joinpath("imageio.swift")))
+    digest = hashlib.sha256(source.read_bytes()).hexdigest()[:16]
+    target = Path.home() / ".cache" / "luvix" / f"imageio-{digest}"
+    if not target.exists():
+        target.parent.mkdir(parents=True, exist_ok=True)
+        result = subprocess.run(
+            ["swiftc", "-O", str(source), "-o", str(target)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode:
+            raise BackendError(f"Swift compilation failed:\n{result.stderr}")
+    return target
+
+
+def run_backend(*args: str) -> str:
+    result = subprocess.run(
+        [str(backend_binary()), *map(str, args)], capture_output=True, text=True, check=False
+    )
+    if result.returncode:
+        raise BackendError(
+            result.stderr.strip() or result.stdout.strip() or "Native backend failed"
+        )
+    return result.stdout.strip()

luvix/backends/apple/hdr_probe.py

@@ -0,0 +1,39 @@
+"""Build and run the isolated macOS HDR decode diagnostic."""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import subprocess
+from importlib.resources import files
+from pathlib import Path
+
+from luvix.backends.apple.bridge import BackendError
+
+
+def run_hdr_probe(source: Path, samples: int) -> str:
+    """Return JSON from the native HDR-aware decode probe."""
+    if platform.system() != "Darwin":
+        raise BackendError("HDR-aware ImageIO decoding requires macOS")
+    swift = Path(str(files("luvix.backends.apple").joinpath("hdr_probe.swift")))
+    digest = hashlib.sha256(swift.read_bytes()).hexdigest()[:16]
+    binary = Path.home() / ".cache" / "luvix" / f"hdr-probe-{digest}"
+    if not binary.exists():
+        binary.parent.mkdir(parents=True, exist_ok=True)
+        result = subprocess.run(
+            ["swiftc", "-O", str(swift), "-o", str(binary)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode:
+            raise BackendError(f"Swift compilation failed:\n{result.stderr}")
+    result = subprocess.run(
+        [str(binary), "inspect-hdr", str(source), str(samples)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode:
+        raise BackendError(result.stderr.strip() or "HDR probe failed")
+    return result.stdout.strip()

luvix/backends/apple/hdr_probe.swift

@@ -0,0 +1,121 @@
+import Foundation
+import CoreGraphics
+import CoreImage
+import ImageIO
+
+func fail(_ message: String) -> Never {
+    fputs("Error: \(message)\n", stderr)
+    exit(1)
+}
+
+let args = CommandLine.arguments
+guard args.count == 4, let count = Int(args[3]), (1...64).contains(count) else {
+    fail("Usage: hdr_probe inspect-hdr SOURCE.HEIC SAMPLES(1..64)")
+}
+let url = URL(fileURLWithPath: args[2])
+guard let source = CGImageSourceCreateWithURL(url as CFURL, nil) else {
+    fail("Cannot open source")
+}
+guard CGImageSourceCopyAuxiliaryDataInfoAtIndex(
+    source, 0, kCGImageAuxiliaryDataTypeHDRGainMap
+) != nil else { fail("No Apple HDR gain map found") }
+
+guard let linearP3 = CGColorSpace(name: CGColorSpace.extendedLinearDisplayP3) else {
+    fail("Extended linear Display P3 unavailable")
+}
+let context = CIContext(options: [
+    .workingColorSpace: linearP3,
+    .outputColorSpace: linearP3,
+    .useSoftwareRenderer: false
+])
+
+struct Result {
+    let report: [String: Any]
+    let sampleValues: [Float]
+}
+
+func measure(_ hdr: Bool) -> Result {
+    // ImageIO requires the decode *request* key, with HDR/SDR as its value.
+    // Using kCGImageSourceDecodeToHDR as the dictionary key silently ignored
+    // the request and produced identical results in both branches.
+    let decodeMode = hdr ? kCGImageSourceDecodeToHDR : kCGImageSourceDecodeToSDR
+    let options: [CFString: Any] = [kCGImageSourceDecodeRequest: decodeMode]
+    guard let decoded = CGImageSourceCreateImageAtIndex(source, 0, options as CFDictionary) else {
+        fail("ImageIO decode failed (HDR=\(hdr))")
+    }
+    let width = decoded.width
+    let height = decoded.height
+    let ci = CIImage(cgImage: decoded)
+    let rowBytes = width * 4 * MemoryLayout<Float>.size
+    var pixels = [Float](repeating: 0, count: width * height * 4)
+    pixels.withUnsafeMutableBytes { bytes in
+        guard let address = bytes.baseAddress else { fail("No bitmap storage") }
+        context.render(
+            ci,
+            toBitmap: address,
+            rowBytes: rowBytes,
+            bounds: CGRect(x: 0, y: 0, width: width, height: height),
+            format: .RGBAf,
+            colorSpace: linearP3
+        )
+    }
+    var minima = [Double](repeating: .infinity, count: 3)
+    var maxima = [Double](repeating: -.infinity, count: 3)
+    var aboveOne = 0
+    var sampled = 0
+    var invalid = 0
+    let stridePixels = max(1, width * height / 100_000)
+    for i in Swift.stride(from: 0, to: width * height, by: stridePixels) {
+        let offset = i * 4
+        let rgb = (0..<3).map { Double(pixels[offset + $0]) }
+        if !rgb.allSatisfy({ $0.isFinite }) { invalid += 1; continue }
+        for c in 0..<3 {
+            minima[c] = min(minima[c], rgb[c])
+            maxima[c] = max(maxima[c], rgb[c])
+        }
+        if rgb.contains(where: { $0 > 1 }) { aboveOne += 1 }
+        sampled += 1
+    }
+    var points: [[String: Any]] = []
+    var sampleValues: [Float] = []
+    for i in 0..<count {
+        let x = (2 * i + 1) * width / (2 * count)
+        let y = height / 2
+        let offset = (y * width + x) * 4
+        let rgb = (0..<3).map { pixels[offset + $0] }
+        sampleValues.append(contentsOf: rgb)
+        points.append(["x": x, "y_raw": y, "rgb_linear_p3": rgb.map(Double.init)])
+    }
+    let report: [String: Any] = [
+        "decoded_bits_per_component": decoded.bitsPerComponent,
+        "rendered_format": "RGBAf_float32",
+        "min_rgb": sampled > 0 ? minima : [0, 0, 0],
+        "max_rgb": sampled > 0 ? maxima : [0, 0, 0],
+        "pixels_above_one": aboveOne,
+        "sampled_pixels": sampled,
+        "invalid_pixels": invalid,
+        "samples": points
+    ]
+    return Result(report: report, sampleValues: sampleValues)
+}
+
+let sdr = measure(false)
+let hdr = measure(true)
+let maxSampleDifference = zip(sdr.sampleValues, hdr.sampleValues)
+    .map { abs(Double($0) - Double($1)) }.max() ?? 0
+let output: [String: Any] = [
+    "source": url.lastPathComponent,
+    "working_space": "extendedLinearDisplayP3",
+    "decode_option": "kCGImageSourceDecodeRequest",
+    "sdr": sdr.report,
+    "hdr": hdr.report,
+    "max_sample_difference": maxSampleDifference,
+    "hdr_decode_distinct_at_sample_points": maxSampleDifference > 1e-6,
+    "note": "Explicit SDR/HDR ImageIO decode requests; compare measured values before accepting reconstruction."
+]
+guard JSONSerialization.isValidJSONObject(output),
+      let data = try? JSONSerialization.data(withJSONObject: output, options: [.sortedKeys]),
+      let json = String(data: data, encoding: .utf8) else {
+    fail("JSON serialization failed")
+}
+print(json)

luvix/backends/apple/hdr_raster.py

@@ -0,0 +1,37 @@
+"""Compile and invoke Apple's full-resolution float HDR raster renderer."""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import subprocess
+from importlib.resources import files
+from pathlib import Path
+
+from luvix.backends.apple.bridge import BackendError
+
+
+def render_hdr_raster(source: Path, prefix: Path) -> None:
+    if platform.system() != "Darwin":
+        raise BackendError("Apple HDR raster export requires macOS")
+    swift = Path(str(files("luvix.backends.apple").joinpath("hdr_raster.swift")))
+    digest = hashlib.sha256(swift.read_bytes()).hexdigest()[:16]
+    binary = Path.home() / ".cache" / "luvix" / f"hdr-raster-{digest}"
+    if not binary.exists():
+        binary.parent.mkdir(parents=True, exist_ok=True)
+        compiled = subprocess.run(
+            ["swiftc", "-O", str(swift), "-o", str(binary)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if compiled.returncode:
+            raise BackendError(f"Swift compilation failed:\n{compiled.stderr}")
+    result = subprocess.run(
+        [str(binary), str(source), str(prefix)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode:
+        raise BackendError(result.stderr.strip() or "HDR raster export failed")

luvix/backends/apple/hdr_raster.swift

@@ -0,0 +1,99 @@
+import Foundation
+import CoreGraphics
+import CoreImage
+import ImageIO
+
+func fail(_ message: String) -> Never {
+    fputs("Error: \(message)\n", stderr)
+    exit(1)
+}
+
+// Write raw interleaved Float32 RGBA in native little-endian order and a JSON sidecar.
+// Raw pixel orientation is retained. Source HEIC is never modified.
+let args = CommandLine.arguments
+guard args.count == 3 else { fail("Usage: hdr_raster SOURCE.HEIC OUTPUT_PREFIX") }
+let sourceURL = URL(fileURLWithPath: args[1])
+let prefix = URL(fileURLWithPath: args[2])
+guard !FileManager.default.fileExists(atPath: prefix.path + ".rgba32f"),
+      !FileManager.default.fileExists(atPath: prefix.path + ".json") else {
+    fail("Refusing to overwrite existing intermediate")
+}
+guard let source = CGImageSourceCreateWithURL(sourceURL as CFURL, nil) else {
+    fail("Cannot open source")
+}
+guard CGImageSourceCopyAuxiliaryDataInfoAtIndex(
+    source, 0, kCGImageAuxiliaryDataTypeHDRGainMap
+) != nil else { fail("No Apple HDR gain map found") }
+let options: [CFString: Any] = [kCGImageSourceDecodeRequest: kCGImageSourceDecodeToHDR]
+guard let decoded = CGImageSourceCreateImageAtIndex(source, 0, options as CFDictionary) else {
+    fail("HDR decode failed")
+}
+// Only use a linear working space with the same primaries as the input.
+// Reject unsupported profiles rather than silently converting to Display P3.
+let baseOptions: [CFString: Any] = [kCGImageSourceDecodeRequest: kCGImageSourceDecodeToSDR]
+guard let base = CGImageSourceCreateImageAtIndex(source, 0, baseOptions as CFDictionary),
+      let sourceSpace = base.colorSpace else { fail("Cannot determine source color space") }
+let sourceName = (sourceSpace.name as String?) ?? ""
+let linearName: CFString
+let sourcePrimaries: String
+if sourceName == (CGColorSpace.displayP3 as String) {
+    linearName = CGColorSpace.extendedLinearDisplayP3
+    sourcePrimaries = "Display P3"
+} else if sourceName == (CGColorSpace.sRGB as String) {
+    linearName = CGColorSpace.extendedLinearSRGB
+    sourcePrimaries = "sRGB"
+} else {
+    fail("Unsupported source color space: \(sourceName). No implicit gamut conversion permitted")
+}
+guard let linearP3 = CGColorSpace(name: linearName) else {
+    fail("Requested linear working color space unavailable")
+}
+let width = decoded.width
+let height = decoded.height
+let rowBytes = width * 4 * MemoryLayout<Float>.size
+let context = CIContext(options: [
+    .workingColorSpace: linearP3,
+    .outputColorSpace: linearP3
+])
+let image = CIImage(cgImage: decoded)
+var pixels = [Float](repeating: 0, count: width * height * 4)
+pixels.withUnsafeMutableBytes { bytes in
+    guard let address = bytes.baseAddress else { fail("Allocation failed") }
+    context.render(
+        image, toBitmap: address, rowBytes: rowBytes,
+        bounds: CGRect(x: 0, y: 0, width: width, height: height),
+        format: .RGBAf, colorSpace: linearP3
+    )
+}
+let finite = pixels.allSatisfy { $0.isFinite }
+guard finite else { fail("Non-finite HDR pixel detected") }
+let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil)
+    as? [String: Any]
+
+let orientation = properties?[kCGImagePropertyOrientation as String]
+    as? Int ?? 1
+let rawURL = URL(fileURLWithPath: prefix.path + ".rgba32f")
+let jsonURL = URL(fileURLWithPath: prefix.path + ".json")
+let payload: [String: Any] = [
+    "width": width, "height": height, "channels": 4,
+    "dtype": "<f4", "layout": "RGBA", "orientation": orientation,
+    "color_space": sourcePrimaries == "Display P3" ? "extendedLinearDisplayP3" : "extendedLinearSRGB",
+    "source_primaries": sourcePrimaries,
+    "decode_request": "kCGImageSourceDecodeToHDR",
+    "reference_white": "relative SDR white = 1.0",
+    "source": sourceURL.lastPathComponent
+]
+guard let metadata = try? JSONSerialization.data(withJSONObject: payload, options: [.sortedKeys]) else {
+    fail("JSON encoding failed")
+}
+do {
+    try FileManager.default.createDirectory(at: prefix.deletingLastPathComponent(), withIntermediateDirectories: true)
+    let rawData = pixels.withUnsafeBytes { Data($0) }
+    try rawData.write(to: rawURL, options: .atomic)
+    try metadata.write(to: jsonURL, options: .atomic)
+    print(String(data: metadata, encoding: .utf8) ?? "{}")
+} catch {
+    try? FileManager.default.removeItem(at: rawURL)
+    try? FileManager.default.removeItem(at: jsonURL)
+    fail("Writing HDR intermediate failed: \(error)")
+}

luvix/backends/apple/icc_profile.py

@@ -0,0 +1,78 @@
+"""Get an Apple-supplied extended-linear Display P3 ICC profile."""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import subprocess
+from importlib.resources import files
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from luvix.backends.apple.bridge import BackendError
+
+
+def linear_display_p3_icc() -> bytes:
+    if platform.system() != "Darwin":
+        raise BackendError("Linear Display P3 ICC extraction requires macOS")
+    swift = Path(str(files("luvix.backends.apple").joinpath("icc_profile.swift")))
+    digest = hashlib.sha256(swift.read_bytes()).hexdigest()[:16]
+    binary = Path.home() / ".cache" / "luvix" / f"icc-profile-{digest}"
+    if not binary.exists():
+        binary.parent.mkdir(parents=True, exist_ok=True)
+        result = subprocess.run(
+            ["swiftc", "-O", str(swift), "-o", str(binary)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode:
+            raise BackendError(f"ICC Swift compilation failed:\n{result.stderr}")
+    with TemporaryDirectory(prefix="luvix-icc-") as directory:
+        destination = Path(directory) / "linear-display-p3.icc"
+        result = subprocess.run(
+            [str(binary), str(destination)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode:
+            raise BackendError(result.stderr.strip() or "ICC extraction failed")
+        return destination.read_bytes()
+
+
+def source_linear_icc(working_space: str) -> bytes:
+    """Return the matching Apple linear ICC; unsupported spaces fail closed."""
+    if working_space not in {"extendedLinearDisplayP3", "extendedLinearSRGB"}:
+        raise BackendError(f"Unsupported working space: {working_space}")
+    return (
+        linear_display_p3_icc()
+        if working_space == "extendedLinearDisplayP3"
+        else _linear_srgb_icc()
+    )
+
+
+def _linear_srgb_icc() -> bytes:
+    import hashlib
+    import subprocess
+    from importlib.resources import files
+    from tempfile import TemporaryDirectory
+
+    swift = Path(str(files("luvix.backends.apple").joinpath("icc_profile.swift")))
+    digest = hashlib.sha256(swift.read_bytes()).hexdigest()[:16]
+    binary = Path.home() / ".cache" / "luvix" / f"icc-profile-{digest}"
+    if not binary.exists():
+        binary.parent.mkdir(parents=True, exist_ok=True)
+        result = subprocess.run(
+            ["swiftc", "-O", str(swift), "-o", str(binary)], capture_output=True, text=True
+        )
+        if result.returncode:
+            raise BackendError(result.stderr)
+    with TemporaryDirectory(prefix="luvix-icc-") as directory:
+        destination = Path(directory) / "linear-srgb.icc"
+        result = subprocess.run(
+            [str(binary), str(destination), "srgb"], capture_output=True, text=True
+        )
+        if result.returncode:
+            raise BackendError(result.stderr.strip())
+        return destination.read_bytes()

luvix/backends/apple/icc_profile.swift

@@ -0,0 +1,31 @@
+import Foundation
+import CoreGraphics
+
+func fail(_ message: String) -> Never {
+    fputs("Error: \(message)\n", stderr)
+    exit(1)
+}
+
+guard (2...3).contains(CommandLine.arguments.count) else {
+    fail("Usage: icc_profile OUTPUT.icc")
+}
+let profileName = CommandLine.arguments.count == 3 ? CommandLine.arguments[2] : "p3"
+let spaceName: CFString = profileName == "srgb"
+    ? CGColorSpace.extendedLinearSRGB : CGColorSpace.extendedLinearDisplayP3
+guard let space = CGColorSpace(name: spaceName) else {
+    fail("Extended linear Display P3 is unavailable")
+}
+guard let profile = space.copyICCData() else {
+    fail("No ICC profile data available for extended linear Display P3")
+}
+let data = profile as Data
+guard data.count >= 128 else { fail("ICC data is unexpectedly short") }
+let declaredSize = data.prefix(4).reduce(UInt32(0)) { ($0 << 8) | UInt32($1) }
+guard declaredSize == data.count else { fail("ICC header length mismatch") }
+guard data.subdata(in: 36..<40) == Data("acsp".utf8) else {
+    fail("ICC signature missing")
+}
+let output = URL(fileURLWithPath: CommandLine.arguments[1])
+do { try data.write(to: output, options: .atomic) }
+catch { fail("Cannot write ICC profile: \(error)") }
+print("Exported extended linear Display P3 ICC (\(data.count) bytes)")

luvix/backends/apple/imageio.swift

@@ -0,0 +1,143 @@
+import Foundation
+import CoreGraphics
+import ImageIO
+import UniformTypeIdentifiers
+
+func die(_ message: String) -> Never { fputs("Error: \(message)\n", stderr); exit(1) }
+func source(_ url: URL) -> CGImageSource {
+    guard let s = CGImageSourceCreateWithURL(url as CFURL, nil) else { die("Cannot open \(url.path)") }
+    return s
+}
+func auxiliary(_ s: CGImageSource) -> [String: Any] {
+    guard let d = CGImageSourceCopyAuxiliaryDataInfoAtIndex(s, 0, kCGImageAuxiliaryDataTypeHDRGainMap) as? [String: Any] else { die("Missing HDR gain map") }
+    return d
+}
+struct MapInfo { let width: Int; let height: Int; let stride: Int; let bytes: Data }
+func mapInfo(_ aux: [String: Any]) -> MapInfo {
+    guard let desc = aux[kCGImageAuxiliaryDataInfoDataDescription as String] as? [String: Any],
+          let w = desc["Width"] as? Int, let h = desc["Height"] as? Int,
+          let stride = desc["BytesPerRow"] as? Int,
+          let format = desc["PixelFormat"] as? Int,
+          let bytes = aux[kCGImageAuxiliaryDataInfoData as String] as? Data,
+          format == 1278226488, w > 0, h > 0, stride >= w, bytes.count == stride*h else {
+        die("Expected Apple L008 grayscale gain map; unsupported layout")
+    }
+    return MapInfo(width: w, height: h, stride: stride, bytes: bytes)
+}
+func grayImage(_ m: MapInfo) -> CGImage {
+    guard let provider = CGDataProvider(data: m.bytes as CFData),
+          let img = CGImage(width: m.width, height: m.height, bitsPerComponent: 8,
+                            bitsPerPixel: 8, bytesPerRow: m.stride,
+                            space: CGColorSpaceCreateDeviceGray(),
+                            bitmapInfo: CGBitmapInfo(rawValue: 0), provider: provider,
+                            decode: nil, shouldInterpolate: false, intent: .defaultIntent) else { die("Could not decode gain map") }
+    return img
+}
+func writePNG(_ image: CGImage, _ url: URL) {
+    guard let d = CGImageDestinationCreateWithURL(url as CFURL, UTType.png.identifier as CFString, 1, nil) else { die("Cannot create PNG") }
+    CGImageDestinationAddImage(d, image, nil)
+    guard CGImageDestinationFinalize(d) else { die("Could not write PNG") }
+}
+func readEditedMap(_ url: URL, original: MapInfo) -> Data {
+    let s = source(url)
+    guard let image = CGImageSourceCreateImageAtIndex(s, 0, nil), image.width == original.width, image.height == original.height else { die("Edited map must have dimensions \(original.width)x\(original.height)") }
+    // Render as 8-bit DeviceGray; preserve original row padding in output buffer.
+    var bytes = [UInt8](original.bytes)
+    let success = bytes.withUnsafeMutableBytes { buffer -> Bool in
+        guard let ctx = CGContext(data: buffer.baseAddress, width: original.width,
+                                  height: original.height, bitsPerComponent: 8,
+                                  bytesPerRow: original.stride,
+                                  space: CGColorSpaceCreateDeviceGray(),
+                                  bitmapInfo: CGImageAlphaInfo.none.rawValue) else { return false }
+        ctx.interpolationQuality = .none
+        ctx.draw(image, in: CGRect(x: 0, y: 0, width: original.width, height: original.height))
+        return true
+    }
+    guard success else { die("Failed rendering edited gain map") }
+    return Data(bytes)
+}
+func writeHEIC(_ base: CGImage, _ original: CGImageSource, _ aux: [String: Any], _ url: URL) {
+    guard let d = CGImageDestinationCreateWithURL(url as CFURL, UTType.heic.identifier as CFString, 1, nil) else { die("Cannot create HEIC") }
+    let props = CGImageSourceCopyPropertiesAtIndex(original, 0, nil)
+    CGImageDestinationAddImage(d, base, props)
+    CGImageDestinationAddAuxiliaryDataInfo(d, kCGImageAuxiliaryDataTypeHDRGainMap, aux as CFDictionary)
+    guard CGImageDestinationFinalize(d) else { die("Could not finalize HEIC") }
+    let check = source(url)
+    _ = mapInfo(auxiliary(check))
+    // ImageIO can mark output files hidden; explicitly clear the flag.
+    let p = Process(); p.executableURL = URL(fileURLWithPath: "/usr/bin/chflags")
+    p.arguments = ["nohidden", url.path]
+    do { try p.run(); p.waitUntilExit() } catch { die("chflags failed: \(error)") }
+    guard p.terminationStatus == 0 else { die("Could not clear hidden flag") }
+}
+
+func details(_ s: CGImageSource) -> [String: Any] {
+    let image = CGImageSourceCreateImageAtIndex(s, 0, nil)!
+    let m = mapInfo(auxiliary(s))
+    let props = CGImageSourceCopyPropertiesAtIndex(s, 0, nil) as? [String: Any] ?? [:]
+    let meta = auxiliary(s)[kCGImageAuxiliaryDataInfoMetadata as String]
+    return ["base_width": image.width, "base_height": image.height,
+            "gain_width": m.width, "gain_height": m.height,
+            "gain_stride": m.stride, "gain_format": "L008",
+            "color_space": image.colorSpace?.name as String? ?? "unknown",
+            "orientation": props[kCGImagePropertyOrientation as String] ?? 1,
+            "has_gainmap_metadata": meta != nil]
+}
+func emitJSON(_ d: [String: Any]) {
+    guard let data = try? JSONSerialization.data(withJSONObject: d, options: [.sortedKeys]),
+          let text = String(data: data, encoding: .utf8) else { die("JSON error") }
+    print(text)
+}
+let args = CommandLine.arguments
+if args.count < 2 { die("Usage: apple_backend inspect|extract|rebuild|validate ...") }
+switch args[1] {
+case "inspect":
+    guard args.count == 3 else { die("inspect source.HEIC") }
+    emitJSON(details(source(URL(fileURLWithPath: args[2]))))
+case "extract":
+    guard args.count == 4 else { die("extract source.HEIC directory") }
+    let input = URL(fileURLWithPath: args[2]); let s = source(input)
+    let dir = URL(fileURLWithPath: args[3], isDirectory: true)
+    do { try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true) } catch { die("Cannot create directory") }
+    for name in ["base.png", "gainmap.png", "manifest.json"] {
+        guard !FileManager.default.fileExists(atPath: dir.appendingPathComponent(name).path) else { die("Refusing to overwrite " + name) }
+    }
+    let base = CGImageSourceCreateImageAtIndex(s, 0, nil)!
+    writePNG(base, dir.appendingPathComponent("base.png"))
+    writePNG(grayImage(mapInfo(auxiliary(s))), dir.appendingPathComponent("gainmap.png"))
+    var report = details(s)
+    report["source_name"] = input.lastPathComponent
+    let data = try! JSONSerialization.data(withJSONObject: report, options: [.prettyPrinted, .sortedKeys])
+    try! data.write(to: dir.appendingPathComponent("manifest.json"))
+    print("Extracted base.png, gainmap.png, manifest.json")
+case "rebuild":
+    guard args.count == 6 else { die("rebuild source.HEIC base.png|- gainmap.png|- output.HEIC") }
+    let original = source(URL(fileURLWithPath: args[2]))
+    let origBase = CGImageSourceCreateImageAtIndex(original, 0, nil)!
+    let base: CGImage
+    if args[3] == "-" { base = origBase }
+    else {
+        let bs = source(URL(fileURLWithPath: args[3]))
+        guard let edited = CGImageSourceCreateImageAtIndex(bs, 0, nil) else { die("Invalid edited base") }
+        base = edited
+    }
+    guard base.width == origBase.width, base.height == origBase.height else { die("Base dimensions mismatch") }
+    guard base.colorSpace?.name == origBase.colorSpace?.name else { die("Base color profile mismatch") }
+    var aux = auxiliary(original)
+    if args[4] != "-" {
+        aux[kCGImageAuxiliaryDataInfoData as String] = readEditedMap(URL(fileURLWithPath: args[4]), original: mapInfo(aux))
+    }
+    let output = URL(fileURLWithPath: args[5])
+    guard !FileManager.default.fileExists(atPath: output.path) else { die("Refusing to overwrite existing output") }
+    writeHEIC(base, original, aux, output)
+    print("Rebuilt: \(output.path)")
+case "validate":
+    guard args.count == 4 else { die("validate source.HEIC output.HEIC") }
+    let a = details(source(URL(fileURLWithPath: args[2])))
+    let b = details(source(URL(fileURLWithPath: args[3])))
+    let keys = ["base_width", "base_height", "gain_width", "gain_height", "gain_format", "color_space", "orientation"]
+    let differences = keys.filter { String(describing: a[$0]) != String(describing: b[$0]) }
+    emitJSON(["valid": differences.isEmpty, "mismatched_fields": differences])
+    if !differences.isEmpty { exit(2) }
+default: die("Unknown command")
+}