GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
//! OpenRaster (`.ora`) read and write. Layout from the public OpenRaster specification
//! (https://www.openraster.org/, `stack.xml` 0.0.x): a ZIP whose first, stored entry is
//! `mimetype` = `image/openraster`, a `stack.xml` layer tree, one PNG per layer, and a
//! `mergedimage.png` / `Thumbnails/thumbnail.png` rendering.
//!
//! Read: raster layers (PNG, any position and size), groups (isolated and pass-through),
//! names, opacity, visibility, `svg:*` and Krita's `krita:*` composite operations, and the
//! `edit-locked` / `alpha-preserve` flags. Everything else is skipped with a warning.
//! Write: raster layers and groups as above; other layer kinds are written as their rendered
//! pixels, layer masks are applied to the pixels, and whatever ORA cannot hold is warned about.

#[cfg(test)]
mod tests;

use photocraft_codecs::{self as codecs, ChannelLayout, Format, Image, SampleType as CSample};
use photocraft_color::{BlendMode, ColorMode, PixelFormat, SampleType};
use photocraft_doc::{Document, Layer, LayerContent};
#[cfg(test)]
use photocraft_format::zip::ZipWriter;
use photocraft_geom::{Rect, Size};
use photocraft_raster::{Interrupt, Surface};

use crate::{ExportResult, ImportResult, IoError};

type Result<T> = std::result::Result<T, IoError>;

/// The `mimetype` entry of an OpenRaster archive (test-only fixture helper).
#[cfg(test)]
pub(crate) const MIMETYPE: &[u8] = b"image/openraster";
/// Decoded pixels across every layer (and the stack.xml) are capped, as for PDN.
pub(crate) const MAX_PIXEL_BYTES: usize = 1 << 30;
/// Canvas side limit (Photoshop's PSB limit).
pub(crate) const MAX_SIDE: u32 = 300_000;
/// Layers and groups in one document.
pub(crate) const MAX_NODES: usize = 8192;
const MAX_ENTRY: usize = 512 << 20;
const THUMBNAIL_SIDE: u32 = 256;

fn invalid(message: impl Into<String>) -> IoError {
    IoError::Ora(message.into())
}

/// `true` for an OpenRaster archive (by its `mimetype` entry).
#[cfg(test)]
pub(crate) fn is_ora(bytes: &[u8]) -> bool {
    craft_ora::is_ora(bytes)
}

/// Blend modes by Krita composite-op id: Krita's `.kra` `compositeop` attribute and the
/// `krita:<id>` composite operations Krita writes into ORA for modes SVG has no name for.
/// Returns the mode and whether it only approximates Krita's formula.
pub(crate) fn krita_blend(id: &str) -> Option<(BlendMode, bool)> {
    use BlendMode as B;
    Some(match id {
        "normal" => (B::Normal, false),
        "multiply" => (B::Multiply, false),
        "screen" => (B::Screen, false),
        "overlay" => (B::Overlay, false),
        "darken" => (B::Darken, false),
        "lighten" => (B::Lighten, false),
        "dodge" => (B::ColorDodge, false),
        "burn" => (B::ColorBurn, false),
        "hard_light" => (B::HardLight, false),
        // Krita's own Soft Light keeps sqrt(cb) over dark backdrops; Photoshop's is the W3C curve.
        "soft_light" => (B::SoftLight, true),
        "soft_light_svg" => (B::SoftLight, false),
        "diff" => (B::Difference, false),
        "exclusion" => (B::Exclusion, false),
        "linear_burn" => (B::LinearBurn, false),
        "linear_dodge" | "add" => (B::LinearDodge, false),
        "subtract" => (B::Subtract, false),
        "divide" => (B::Divide, false),
        "vivid_light" => (B::VividLight, false),
        "linear light" => (B::LinearLight, false),
        "pin_light" => (B::PinLight, false),
        "hard_mix_photoshop" => (B::HardMix, false),
        // Krita's own Hard Mix thresholds differently from Photoshop's.
        "hard mix" => (B::HardMix, true),
        "darker color" => (B::DarkerColor, false),
        "lighter color" => (B::LighterColor, false),
        "hue" => (B::Hue, false),
        "saturation" => (B::Saturation, false),
        "color" => (B::Color, false),
        "luminize" => (B::Luminosity, false),
        "dissolve" => (B::Dissolve, false),
        "reflect" => (B::Reflect, false),
        "glow" => (B::Glow, false),
        "negation" => (B::Negation, false),
        "xor" => (B::Xor, true),
        _ => return None,
    })
}

/// The Krita composite-op id written for `mode` (`None` for modes Krita has no counterpart for).
pub(crate) fn krita_id(mode: BlendMode) -> Option<&'static str> {
    use BlendMode as B;
    Some(match mode {
        B::Normal | B::PassThrough => "normal",
        B::Dissolve => "dissolve",
        B::Darken => "darken",
        B::Multiply => "multiply",
        B::ColorBurn => "burn",
        B::LinearBurn => "linear_burn",
        B::DarkerColor => "darker color",
        B::Lighten => "lighten",
        B::Screen => "screen",
        B::ColorDodge => "dodge",
        B::LinearDodge => "linear_dodge",
        B::LighterColor => "lighter color",
        B::Overlay => "overlay",
        B::SoftLight => "soft_light_svg",
        B::HardLight => "hard_light",
        B::VividLight => "vivid_light",
        B::LinearLight => "linear light",
        B::PinLight => "pin_light",
        B::HardMix => "hard_mix_photoshop",
        B::Difference => "diff",
        B::Exclusion => "exclusion",
        B::Subtract => "subtract",
        B::Divide => "divide",
        B::Hue => "hue",
        B::Saturation => "saturation",
        B::Color => "color",
        B::Luminosity => "luminize",
        B::Reflect => "reflect",
        B::Glow => "glow",
        B::Negation => "negation",
        B::Xor | B::PaintNetColorBurn | B::PaintNetColorDodge => return None,
    })
}

/// The SVG compositing names of the OpenRaster specification.
const SVG_OPS: [(&str, BlendMode); 15] = [
    ("svg:src-over", BlendMode::Normal),
    ("svg:multiply", BlendMode::Multiply),
    ("svg:screen", BlendMode::Screen),
    ("svg:overlay", BlendMode::Overlay),
    ("svg:darken", BlendMode::Darken),
    ("svg:lighten", BlendMode::Lighten),
    ("svg:color-dodge", BlendMode::ColorDodge),
    ("svg:color-burn", BlendMode::ColorBurn),
    ("svg:hard-light", BlendMode::HardLight),
    ("svg:soft-light", BlendMode::SoftLight),
    ("svg:difference", BlendMode::Difference),
    ("svg:color", BlendMode::Color),
    ("svg:luminosity", BlendMode::Luminosity),
    ("svg:hue", BlendMode::Hue),
    ("svg:saturation", BlendMode::Saturation),
];

/// A composite-op attribute as a blend mode; unknown names fall back to Normal with a warning.
fn composite_op(op: &str, layer: &str, warnings: &mut Warnings) -> BlendMode {
    if let Some((_, mode)) = SVG_OPS.iter().find(|(name, _)| *name == op) {
        return *mode;
    }
    match op {
        "svg:plus" => return BlendMode::LinearDodge,
        // Not in the specification's list, but written by several applications.
        "svg:exclusion" => return BlendMode::Exclusion,
        _ => {}
    }
    if let Some((mode, approx)) = op.strip_prefix("krita:").and_then(krita_blend) {
        if approx {
            warnings.note(&format!("Krita's {op} blend mode is approximated by {}", mode.label()));
        }
        return mode;
    }
    warnings.layer(layer, &format!("composite operation {op} is not supported; it opens as Normal"));
    BlendMode::Normal
}

/// Warnings gathered during import, each distinct message once; per-layer ones are grouped.
#[derive(Default)]
pub(crate) struct Warnings {
    general: Vec<String>,
    per_layer: Vec<(String, Vec<String>)>,
}

impl Warnings {
    pub(crate) fn note(&mut self, message: &str) {
        if !self.general.iter().any(|m| m == message) {
            self.general.push(message.to_string());
        }
    }
    pub(crate) fn layer(&mut self, layer: &str, message: &str) {
        match self.per_layer.iter_mut().find(|(m, _)| m == message) {
            Some((_, layers)) => {
                if !layers.iter().any(|l| l == layer) {
                    layers.push(layer.to_string());
                }
            }
            None => self.per_layer.push((message.to_string(), vec![layer.to_string()])),
        }
    }
    pub(crate) fn finish(self) -> Vec<String> {
        let mut out = self.general;
        for (message, layers) in self.per_layer {
            let shown: Vec<String> = layers.iter().take(5).map(|l| format!("\"{l}\"")).collect();
            let more = layers.len().saturating_sub(5);
            let tail = if more > 0 { format!(" and {more} more") } else { String::new() };
            out.push(format!("{} ({}{tail})", message, shown.join(", ")));
        }
        out
    }
}

/// A number attribute; a missing one is `default`, an unparsable one an error.
/// OpenRaster 0.0.6 defaults to isolated groups and makes `auto` explicitly pass-through.
/// Older files used inference from the group's blend mode; keep that behavior when the
/// version is absent or unrecognized, too. Compare the numeric core, not version strings.
fn uses_explicit_group_isolation(version: Option<&str>) -> bool {
    let Some(core) = version.and_then(|v| v.trim().split(['-', '+']).next()) else { return false };
    let mut parts = core.split('.');
    let number = |part: Option<&str>| part.and_then(|s| s.parse::<u32>().ok());
    match (number(parts.next()), number(parts.next()), number(parts.next()), parts.next()) {
        (Some(major), Some(minor), Some(patch), None) => [major, minor, patch] >= [0, 0, 6],
        _ => false,
    }
}

struct Reader<'a, 'c> {
    archive: craft_ora::Archive<'a>,
    ctl: &'c Interrupt<'c>,
    explicit_group_isolation: bool,
    nodes: usize,
    budget: usize,
    warnings: Warnings,
    /// Decoded layer PNGs, converted to the document depth once every layer is known.
    images: Vec<Image>,
}

/// A layer as read, before its pixels are converted to the document's format.
enum Node {
    Raster { layer: Layer, image: Option<usize>, x: i32, y: i32 },
    Group { layer: Layer, children: Vec<Node> },
}

impl Reader<'_, '_> {
    fn png(&mut self, src: &str, layer: &str) -> Result<Option<usize>> {
        let Some(data) = self.archive.entry(src, MAX_ENTRY).map_err(|e| invalid(format!("{src}: {e}")))? else {
            self.warnings.layer(layer, "the layer's image is missing from the archive; the layer opens empty");
            return Ok(None);
        };
        let mut opts = codecs::DecodeOptions::default();
        opts.limits.max_width = MAX_SIDE;
        opts.limits.max_height = MAX_SIDE;
        opts.limits.max_alloc = self.budget as u64;
        let image = codecs::decode_with(&data, &opts).map_err(|e| invalid(format!("{src}: {e}")))?;
        let (w, h) = image.dimensions();
        let rgba16 = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(8)).ok_or_else(|| invalid("layer image size overflow"))?;
        self.budget = self.budget.checked_sub(rgba16).ok_or_else(|| invalid("decoded layers exceed the 1 GiB limit"))?;
        if !matches!(codecs::detect(&data), Some(Format::Png)) {
            self.warnings.note("some layer images are not PNG, as OpenRaster expects; they were read anyway");
        }
        self.images.push(image);
        Ok(Some(self.images.len() - 1))
    }

    fn stack(&mut self, stack: &[craft_ora::Node], depth: usize) -> Result<Vec<Node>> {
        if depth > photocraft_doc::MAX_GROUP_DEPTH {
            return Err(IoError::Unsupported(format!("layer groups nested deeper than {}", photocraft_doc::MAX_GROUP_DEPTH)));
        }
        let mut out = Vec::new();
        for child in stack {
            self.ctl.check().map_err(|_| IoError::Cancelled)?;
            self.nodes += 1;
            if self.nodes > MAX_NODES {
                return Err(invalid(format!("more than {MAX_NODES} layers")));
            }
            let index = self.nodes;
            match child {
                craft_ora::Node::Layer(record) => {
                    let mut layer = Layer::raster("", PixelFormat::RGBA8);
                    layer.name = record.props.name.as_deref().filter(|s| !s.trim().is_empty()).map_or_else(|| format!("Layer {index}"), str::to_string);
                    layer.visible = record.props.visible;
                    layer.opacity = record.props.opacity.clamp(0.0, 1.0);
                    layer.blend = composite_op(record.props.composite_op.as_deref().unwrap_or("svg:src-over"), &layer.name, &mut self.warnings);
                    layer.locks.all = record.props.edit_locked;
                    layer.locks.transparency = record.props.alpha_preserve;
                    let image = match record.src.as_deref() {
                        Some(src) => self.png(src, &layer.name.clone())?,
                        None => {
                            self.warnings.layer(&layer.name, "the layer has no image; it opens empty");
                            None
                        }
                    };
                    out.push(Node::Raster { layer, image, x: record.x, y: record.y });
                }
                craft_ora::Node::Stack(record) => {
                    let mut layer = Layer::group("", Vec::new());
                    layer.name = record.props.name.as_deref().filter(|s| !s.trim().is_empty()).map_or_else(|| format!("Layer {index}"), str::to_string);
                    layer.visible = record.props.visible;
                    layer.opacity = record.props.opacity.clamp(0.0, 1.0);
                    layer.blend = composite_op(record.props.composite_op.as_deref().unwrap_or("svg:src-over"), &layer.name, &mut self.warnings);
                    layer.locks.all = record.props.edit_locked;
                    layer.locks.transparency = record.props.alpha_preserve;
                    let isolation = record.isolation.as_deref();
                    let pass_through = if self.explicit_group_isolation {
                        // Since 0.0.6 only explicit `auto` passes through, ignoring the
                        // group's composite-op. An omitted isolation means `isolate`.
                        isolation == Some("auto")
                    } else {
                        isolation != Some("isolate") && layer.blend == BlendMode::Normal
                    };
                    if pass_through {
                        layer.blend = BlendMode::PassThrough;
                    }
                    let children = self.stack(&record.children, depth + 1)?;
                    out.push(Node::Group { layer, children });
                }
                craft_ora::Node::Other { tag, name } => {
                    let name = name.as_deref().unwrap_or(tag).to_string();
                    self.warnings.layer(&name, &format!("OpenRaster <{tag}> elements are not supported and were skipped"));
                }
            }
        }
        Ok(out)
    }
}

/// Sample depth of the document: the deepest layer image (8 or 16 bit; float stays float).
fn document_depth(images: &[Image]) -> SampleType {
    images.iter().fold(SampleType::U8, |d, i| match (d, i.sample_type()) {
        (SampleType::F32, _) | (_, CSample::F32 | CSample::F16) => SampleType::F32,
        (SampleType::U16, _) | (_, CSample::U16) => SampleType::U16,
        _ => SampleType::U8,
    })
}

pub(crate) fn csample(depth: SampleType) -> CSample {
    crate::flat::csample(depth)
}

/// Builds the document tree bottom-to-top (stack.xml lists the topmost node first).
fn build(nodes: Vec<Node>, images: &[Image], fmt: PixelFormat, budget: &mut usize, ctl: &Interrupt<'_>) -> Result<Vec<Layer>> {
    let mut out = Vec::with_capacity(nodes.len());
    for node in nodes.into_iter().rev() {
        ctl.check().map_err(|_| IoError::Cancelled)?;
        match node {
            Node::Raster { mut layer, image, x, y } => {
                let mut surface = Surface::new(fmt);
                if let Some(image) = image.and_then(|i| images.get(i)) {
                    let (w, h) = image.dimensions();
                    let px = image.convert(ChannelLayout::Rgba, csample(fmt.sample));
                    let rect = Rect::new(x, y, x.saturating_add(w as i32), y.saturating_add(h as i32));
                    if rect.width() != w || rect.height() != h || px.data().len() != (w as usize) * (h as usize) * fmt.bytes_per_pixel() {
                        return Err(invalid("layer image does not fit its position"));
                    }
                    // Admitted by decoded size; the surface stores whole tiles, many more for a
                    // narrow image or one offset across tile edges.
                    // The check stays before the write (it allocates the whole rect's tiles); only the
                    // tiles kept after `prune()` are charged.
                    let tiles = usize::try_from(photocraft_raster::tile_storage_bytes(rect, &fmt)).unwrap_or(usize::MAX);
                    if tiles > *budget {
                        return Err(invalid("decoded layers exceed the 1 GiB limit"));
                    }
                    surface.write_interleaved(rect, px.data());
                    surface.prune();
                    let kept = usize::try_from(photocraft_raster::stored_tiles_bytes(surface.tile_count() as u64, &fmt)).unwrap_or(usize::MAX);
                    *budget = budget.saturating_sub(kept);
                }
                layer.content = LayerContent::Raster(surface);
                out.push(layer);
            }
            Node::Group { mut layer, children } => {
                let children = build(children, images, fmt, budget, ctl)?;
                if let Some(c) = layer.children_mut() {
                    *c = children;
                }
                out.push(layer);
            }
        }
    }
    Ok(out)
}

pub(crate) fn import(name: &str, bytes: &[u8], ctl: &Interrupt<'_>) -> Result<ImportResult> {
    let archive = craft_ora::Archive::open(bytes).map_err(|e| invalid(e.to_string()))?;
    let image = archive.image().clone();
    let (w, h) = (image.width, image.height);
    if w > MAX_SIDE || h > MAX_SIDE {
        return Err(invalid(format!("image size {w}×{h} exceeds {MAX_SIDE} pixels per side")));
    }
    if (w as usize).saturating_mul(h as usize).saturating_mul(8) > MAX_PIXEL_BYTES {
        return Err(invalid("the canvas exceeds the 1 GiB pixel limit"));
    }
    let mut reader = Reader {
        archive,
        ctl,
        explicit_group_isolation: uses_explicit_group_isolation(image.version.as_deref()),
        nodes: 0,
        budget: MAX_PIXEL_BYTES,
        warnings: Warnings::default(),
        images: Vec::new(),
    };
    let nodes = reader.stack(&image.stack, 1)?;
    ctl.progress(0.8);
    let depth = document_depth(&reader.images);
    if depth == SampleType::F32 {
        reader.warnings.note("float layer images open as a 32-bit float document");
    }
    let fmt = PixelFormat::new(ColorMode::Rgb, depth, true);
    let mut document = Document::new(name, Size::new(w, h), ColorMode::Rgb, depth);
    document.layers = build(nodes, &reader.images, fmt, &mut reader.budget, ctl)?;
    let xres = image.xres;
    let yres = image.yres;
    if xres > 0.0 && xres < 1.0e6 {
        document.resolution_dpi = xres as f32;
        reader.warnings.general.extend(crate::unequal_resolution_warning(xres, yres));
    }
    if document.layers.is_empty() {
        reader.warnings.note("the OpenRaster file has no layers");
    }
    Ok(ImportResult { document, warnings: reader.warnings.finish(), source_read_only: false, preview_only: false })
}

// ---------------------------------------------------------------------------------------------
// Export

/// The composite-op attribute for `mode`: the SVG name where the specification has one, else
/// Krita's (`krita:<id>`, which Krita reads back and others treat as Normal).
fn op_name(mode: BlendMode) -> Option<String> {
    match mode {
        BlendMode::PassThrough => Some("svg:src-over".into()),
        BlendMode::LinearDodge => Some("svg:plus".into()),
        m => SVG_OPS.iter().find(|(_, s)| *s == m).map(|(n, _)| (*n).to_string()).or_else(|| krita_id(m).map(|id| format!("krita:{id}"))),
    }
}

struct Writer<'a> {
    doc: &'a Document,
    archive: craft_ora::Writer,
    next: usize,
    sample: CSample,
    warnings: Warnings,
    /// Only collect the warnings ([`losses`]): no pixels are rendered or encoded.
    dry: bool,
}

/// Straight RGBA floats as interleaved PNG samples at `sample` depth.
fn encode_rgba(px: &[[f32; 4]], sample: CSample) -> Vec<u8> {
    match sample {
        CSample::U16 => px.iter().flat_map(|p| p.map(|v| ((v.clamp(0.0, 1.0) * 65535.0 + 0.5) as u16).to_ne_bytes())).flatten().collect(),
        _ => px.iter().flat_map(|p| p.map(|v| (v.clamp(0.0, 1.0) * 255.0 + 0.5) as u8)).collect(),
    }
}

fn png(w: u32, h: u32, px: &[[f32; 4]], sample: CSample) -> Result<Vec<u8>> {
    let image = Image::from_raw(w, h, ChannelLayout::Rgba, sample, encode_rgba(px, sample))?;
    let opts = codecs::EncodeOptions { embed_icc: false, ..Default::default() };
    Ok(codecs::encode(&image, Format::Png, &opts)?)
}

/// `px` (row-major over `rect`) cut down to the pixels that aren't fully transparent, with
/// transparent pixels zeroed, so masked-out or empty margins aren't written.
/// Most bytes of straight RGBA floats one layer may take while it is written. A layer is one PNG
/// of its content's bounding box, so a few pixels far apart make a box of mostly nothing; refuse
/// that rather than allocate it. 1.5 × [`MAX_ENTRY`] of floats is at most 8 B/px × a third of that
/// raw, so the PNG stays within what [`Reader::png`] will read back.
const MAX_EXPORT_LAYER_BYTES: u64 = 3 * MAX_ENTRY as u64 / 2;

fn admit_layer(rect: Rect) -> Result<()> {
    let bytes = u64::from(rect.width()).saturating_mul(u64::from(rect.height())).saturating_mul(std::mem::size_of::<[f32; 4]>() as u64);
    if bytes > MAX_EXPORT_LAYER_BYTES {
        return Err(IoError::Unsupported(format!("a {}×{} layer is too large to save to OpenRaster", rect.width(), rect.height())));
    }
    Ok(())
}

fn crop(rect: Rect, mut px: Vec<[f32; 4]>) -> (Rect, Vec<[f32; 4]>) {
    let w = rect.width() as usize;
    if w == 0 {
        return (Rect::EMPTY, Vec::new());
    }
    let (mut x0, mut y0, mut x1, mut y1) = (usize::MAX, usize::MAX, 0, 0);
    for (i, p) in px.iter_mut().enumerate() {
        if p[3] <= 0.0 {
            *p = [0.0; 4];
            continue;
        }
        let (x, y) = (i % w, i / w);
        (x0, y0, x1, y1) = (x0.min(x), y0.min(y), x1.max(x + 1), y1.max(y + 1));
    }
    if x0 >= x1 {
        return (Rect::EMPTY, Vec::new());
    }
    if (x0, y0, x1) == (0, 0, w) && y1 == px.len() / w {
        return (rect, px);
    }
    let out = (y0..y1).flat_map(|y| px.get(y * w + x0..y * w + x1).unwrap_or_default().iter().copied()).collect();
    (Rect::new(rect.x0 + x0 as i32, rect.y0 + y0 as i32, rect.x0 + x1 as i32, rect.y0 + y1 as i32), out)
}

impl Writer<'_> {
    fn common(&mut self, layer: &Layer) -> craft_ora::Props {
        let op = op_name(layer.blend).unwrap_or_else(|| {
            self.warnings.layer(&layer.name, &format!("the {} blend mode has no OpenRaster equivalent; it was saved as Normal", layer.blend.label()));
            "svg:src-over".to_string()
        });
        // OpenRaster's one edit lock reopens as Lock All; it has no position lock (#7018).
        if layer.locks.pixels && !layer.locks.all {
            self.warnings.layer(&layer.name, "Lock Image Pixels was saved as OpenRaster's edit lock; it reopens as Lock All");
        }
        // The Background's position lock is part of being the Background, not one the user set:
        // every new document has it, and OpenRaster has no Background to keep it on.
        if layer.locks.position && !layer.locks.all && !self.doc.is_background(layer.id) {
            self.warnings.layer(&layer.name, "Lock Position is not saved to OpenRaster");
        }
        if layer.clipped {
            self.warnings.layer(&layer.name, "OpenRaster has no clipping masks; these layers were saved unclipped");
        }
        if !layer.effects.items.is_empty() || layer.effects.psd_raw.is_some() {
            self.warnings.layer(&layer.name, "layer styles are not saved to OpenRaster");
        }
        if layer.vector_mask.as_ref().is_some_and(|m| m.enabled) {
            self.warnings.layer(&layer.name, "vector masks are not saved to OpenRaster");
        }
        if layer.fill_opacity < 1.0 {
            if matches!(&layer.content, LayerContent::Group(_)) {
                self.warnings.layer(&layer.name, "fill opacity was combined into the layer opacity");
            } else {
                self.warnings.layer(&layer.name, "fill opacity was applied to the saved layer pixels");
            }
        }
        craft_ora::Props {
            name: Some(layer.name.clone()),
            visible: layer.visible,
            // OpenRaster has one opacity for groups; fold fill opacity into it because groups
            // have no pixel payload in which to bake it.
            opacity: if matches!(&layer.content, LayerContent::Group(_)) {
                (layer.opacity * layer.fill_opacity).clamp(0.0, 1.0)
            } else {
                layer.opacity.clamp(0.0, 1.0)
            },
            composite_op: Some(op),
            edit_locked: layer.locks.all || layer.locks.pixels,
            alpha_preserve: layer.locks.transparency,
        }
    }

    /// What saving a non-group layer's pixels loses: a type, shape, fill or smart object layer
    /// becomes pixels, and its pixel mask is applied to them.
    fn content_warnings(&mut self, layer: &Layer) {
        if !matches!(layer.content, LayerContent::Raster(_)) {
            self.warnings.layer(&layer.name, &format!("{} layers are saved to OpenRaster as pixels", layer.content.kind_name().to_lowercase()));
        }
        if let Some(mask) = layer.mask.as_ref().filter(|m| m.enabled) {
            if mask.feather > 0.0 {
                self.warnings.layer(&layer.name, "layer mask feathering is not applied in OpenRaster");
            }
            self.warnings.layer(&layer.name, "layer masks were applied to the layer pixels");
        }
    }

    /// The layer's own pixels (straight RGBA floats) and their bounds; its pixel mask applied.
    fn pixels(&mut self, layer: &Layer) -> Result<(Rect, Vec<[f32; 4]>)> {
        let canvas = self.doc.bounds();
        let (rect, mut buf) = match &layer.content {
            LayerContent::Raster(s) => {
                let r = s.content_bounds();
                admit_layer(r)?;
                (r, photocraft_compose::surface_to_buffer(s, r).into_px())
            }
            _ => {
                // Rendered as it shows on its own, before the layer's blending options.
                let mut solo = layer.clone();
                solo.visible = true;
                solo.opacity = 1.0;
                solo.fill_opacity = 1.0;
                solo.blend = BlendMode::Normal;
                solo.clipped = false;
                solo.mask = None;
                solo.effects = Default::default();
                let r = photocraft_compose::composite_bounds(&solo, canvas).unwrap_or(canvas).intersect(&canvas);
                admit_layer(r)?;
                (r, photocraft_compose::render_layer(&solo, r).into_px())
            }
        };
        if let Some(mask) = layer.mask.as_ref().filter(|m| m.enabled) {
            let mut values = Vec::new();
            mask.values_into(rect, &mut values);
            for (p, m) in buf.iter_mut().zip(values) {
                p[3] *= m;
            }
        }
        if layer.fill_opacity < 1.0 {
            for p in &mut buf {
                p[3] *= layer.fill_opacity.clamp(0.0, 1.0);
            }
        }
        Ok(crop(rect, buf))
    }

    fn layers(&mut self, layers: &[Layer], depth: usize) -> Result<Vec<craft_ora::Node>> {
        if depth > photocraft_doc::MAX_GROUP_DEPTH {
            return Err(IoError::Unsupported(format!("layer groups nested deeper than {}", photocraft_doc::MAX_GROUP_DEPTH)));
        }
        let mut nodes = Vec::new();
        // stack.xml lists the topmost layer first.
        for layer in layers.iter().rev() {
            match &layer.content {
                LayerContent::Group(g) => {
                    let props = self.common(layer);
                    let isolation = if layer.blend == BlendMode::PassThrough { "auto" } else { "isolate" };
                    if layer.mask.as_ref().is_some_and(|m| m.enabled) {
                        self.warnings.layer(&layer.name, "group masks are not saved to OpenRaster");
                    }
                    nodes.push(craft_ora::Node::Stack(craft_ora::Stack {
                        props,
                        isolation: Some(isolation.to_string()),
                        children: self.layers(&g.children, depth + 1)?,
                    }));
                }
                LayerContent::Adjustment(_) => {
                    self.warnings.layer(&layer.name, "adjustment layers cannot be saved to OpenRaster and were left out (the merged image keeps their look)");
                }
                _ => {
                    let props = self.common(layer);
                    self.content_warnings(layer);
                    if self.dry {
                        continue;
                    }
                    let (rect, px) = self.pixels(layer)?;
                    let (rect, px) = if rect.is_empty() { (Rect::from_xywh(0, 0, 1, 1), vec![[0.0; 4]]) } else { (rect, px) };
                    let src = format!("data/layer{}.png", self.next);
                    self.next += 1;
                    let data = png(rect.width(), rect.height(), &px, self.sample)?;
                    self.archive.add(&src, &data).map_err(|e| IoError::Ora(e.to_string()))?;
                    nodes.push(craft_ora::Node::Layer(craft_ora::Layer { props, x: rect.x0, y: rect.y0, src: Some(src) }));
                }
            }
        }
        Ok(nodes)
    }
}

pub(crate) fn export(doc: &Document) -> Result<ExportResult> {
    if !matches!(doc.mode, ColorMode::Rgb | ColorMode::Grayscale) {
        return Err(IoError::Unsupported("OpenRaster holds RGB layers; convert the document to RGB or Grayscale first".into()));
    }
    let sample = match doc.depth {
        SampleType::U8 => CSample::U8,
        _ => CSample::U16,
    };
    let mut w = Writer { doc, archive: craft_ora::Writer::new(), next: 0, sample, warnings: Warnings::default(), dry: false };
    document_warnings(doc, &mut w.warnings);
    let stack = w.layers(&doc.layers, 1)?;
    w.archive
        .add_stack(&craft_ora::Image {
            version: Some("0.0.6".into()),
            width: doc.size.width,
            height: doc.size.height,
            xres: f64::from(doc.resolution_dpi.round().max(1.0)),
            yres: f64::from(doc.resolution_dpi.round().max(1.0)),
            stack,
        })
        .map_err(|e| IoError::Ora(e.to_string()))?;
    let merged = photocraft_compose::flatten(doc);
    w.archive.add("mergedimage.png", &png(doc.size.width, doc.size.height, &merged.px, sample)?).map_err(|e| IoError::Ora(e.to_string()))?;
    let thumb = photocraft_compose::thumbnail(doc, THUMBNAIL_SIDE);
    let thumb = Image::from_raw(thumb.width, thumb.height, ChannelLayout::Rgba, CSample::U8, thumb.pixels)?;
    w.archive
        .add("Thumbnails/thumbnail.png", &codecs::encode(&thumb, Format::Png, &codecs::EncodeOptions::default())?)
        .map_err(|e| IoError::Ora(e.to_string()))?;
    Ok(ExportResult { bytes: w.archive.finish().map_err(|e| IoError::Ora(e.to_string()))?, warnings: w.warnings.finish() })
}

/// What saving `doc` to OpenRaster loses that isn't in a layer.
fn document_warnings(doc: &Document, warnings: &mut Warnings) {
    if doc.depth == SampleType::F32 {
        warnings.note("32-bit float layers are saved as 16-bit PNGs");
    }
    if !doc.channels.is_empty() {
        warnings.note("alpha channels are not saved to OpenRaster");
    }
    if !doc.metadata.text.is_empty() || doc.metadata.xmp.is_some() || doc.metadata.exif.is_some() {
        warnings.note("metadata (XMP, EXIF, text) is not saved to OpenRaster");
    }
    // Readers assume sRGB, so an sRGB document loses nothing by the missing tag.
    let srgb = |bytes: &[u8]| craft_cms::Profile::parse(bytes).is_ok_and(|p| p.same_colors(craft_cms::Builtin::Srgb.profile()));
    if doc.icc_profile.as_deref().is_some_and(|b| !srgb(b)) {
        warnings.note("the colour profile is not saved to OpenRaster; readers assume sRGB");
    }
    if doc.mode == ColorMode::Grayscale {
        warnings.note("grayscale layers are saved as RGB");
    }
}

/// Everything saving `doc` to OpenRaster would lose (the warnings [`export`] gives), without
/// rendering or encoding anything. Empty when an OpenRaster file holds the whole document, so it
/// can be the document's own file; otherwise a save to OpenRaster is a copy (#3806).
pub fn losses(doc: &Document) -> Vec<String> {
    if !matches!(doc.mode, ColorMode::Rgb | ColorMode::Grayscale) {
        return vec!["OpenRaster holds RGB layers; convert the document to RGB or Grayscale first".into()];
    }
    let mut w = Writer { doc, archive: craft_ora::Writer::new(), next: 0, sample: CSample::U8, warnings: Warnings::default(), dry: true };
    document_warnings(doc, &mut w.warnings);
    if let Err(e) = w.layers(&doc.layers, 1) {
        w.warnings.note(&e.to_string());
    }
    w.warnings.finish()
}