GitCorner

Code

ossartcrafttexturecraft๐ŸŒ
d84914ef1e5a
//! `file.importPbrFolder` and `file.scanPbrFolder`: a folder (or selected files, or a `.zip`) of
//! PBR texture maps becomes one fill layer, like `file.importMaterialX` does for a `.mtlx`.
//!
//! The maps are found by file name ([`texturecraft_formats::pbr_maps`]: albedo, roughness,
//! metallic, normal with its OpenGL / DirectX convention, height, occlusion, emissive, opacity,
//! packed ORM). A packed ORM image is split into three single-channel resources, a glossiness
//! map is inverted into roughness, and every other map keeps its original bytes as the resource.
//! The folder is untrusted: symbolic links and other non-regular files are not followed, every
//! file and the whole import are size-capped, and an image that cannot be decoded is skipped with a
//! warning while the rest is imported. The whole import is one undo step. A programmatic call never
//! asks: when several files name one map the best is used and the others are listed in
//! `candidates`, so a caller can scan first (`file.scanPbrFolder`) and pass `choose`.

use std::collections::BTreeMap;
use std::sync::Arc;

use serde_json::{Value, json};
use texturecraft_core::{Channel, Fill, Layer, LayerKind, NormalFormat, Source};
use texturecraft_formats::pbr_maps::{self, MapKind, PbrSet};

use crate::commands::{CommandSpec, always, bad, strp};
use crate::{EngineError, Result, Session, cmd};

/// Most files looked at in one folder or archive.
pub const MAX_FILES: usize = 4096;
/// Largest single image file read.
pub const MAX_FILE_BYTES: u64 = 256 << 20;
/// Largest decoded image (width ร— height).
pub const MAX_IMAGE_TEXELS: u64 = 64 << 20;
/// Largest sum of decoded texels in one import.
pub const MAX_TOTAL_TEXELS: u64 = 320 << 20;
/// Upper bound on the import's estimated decoded and temporary image memory.
const MAX_IMPORT_MEMORY_BYTES: u64 = 4 << 30;
/// Leave most available memory to the document, renderer, and operating system.
const IMPORT_MEMORY_SHARE: u64 = 4;
const RGBA_FLOAT_BYTES_PER_TEXEL: u64 = 16;
/// Headroom for the decoder and one generated-map conversion in flight.
const IMPORT_TEMP_BYTES_PER_TEXEL: u64 = 32;

fn import_memory_budget() -> u64 {
    #[cfg(not(target_arch = "wasm32"))]
    let available_bytes = texturecraft_formats::available_save_resources().1;
    #[cfg(target_arch = "wasm32")]
    let available_bytes = MAX_IMPORT_MEMORY_BYTES;

    (available_bytes / IMPORT_MEMORY_SHARE).min(MAX_IMPORT_MEMORY_BYTES)
}

fn allowed_source_texels(budget_bytes: u64, retained_bytes: u64, output_count: usize) -> u64 {
    // A source and each output retain RGBA floats; leave room for decoding and conversion
    let retained_per_texel = RGBA_FLOAT_BYTES_PER_TEXEL * (1 + output_count as u64);
    let temporary_per_texel = IMPORT_TEMP_BYTES_PER_TEXEL;
    budget_bytes.saturating_sub(retained_bytes) / (retained_per_texel + temporary_per_texel)
}

pub fn specs() -> Vec<CommandSpec> {
    vec![
        cmd!(
            "file.importPbrFolder",
            "Import PBR texture folder...",
            ["File"],
            None,
            "{path: a folder or .zip of PBR maps, or files: [paths], name?: layer name, normalFormat?: auto|openGl|directX (auto: from _gl/_dx in the name, else openGl; a value forces it), projection?: uv|triplanar|planar..., scale?, choose?: {map id: file} for maps with several candidates} โ†’ {layer, name, maps, candidates, normalFormat, channels, resources, ignored, warnings}: one fill layer; maps are found by file name (baseColor, roughness, glossiness, metallic, normal, height, ambientOcclusion, emissive, opacity, orm); packed ORM is split, glossiness inverted",
            always,
            import
        ),
        cmd!(
            "file.scanPbrFolder",
            "Scan PBR texture folder",
            [],
            None,
            "{path | files, name?, normalFormat?, choose?, projection?, scale?} โ†’ {name, maps, candidates, normalFormat, channelsAvailable, ignored}: native paths only; validates import options without decoding or changing the project",
            always,
            scan
        ),
    ]
}

/// One file offered to the importer: its name (folders joined by `/`) and size.
pub type FileList = Vec<(String, u64)>;
/// Reads a file of the list by name.
pub type Loader<'a> = &'a dyn Fn(&str) -> std::result::Result<Vec<u8>, String>;

mod pbr_options;
mod take;

pub use pbr_options::PbrOptions;
use take::Take;

/// The detection for a file list with the caller's choices applied.
fn detect_with(files: &FileList, choose: &BTreeMap<MapKind, String>) -> Result<PbrSet> {
    let mut set = pbr_maps::detect(files.iter().map(|(n, s)| (n.as_str(), *s)));
    for (kind, file) in choose {
        let list = set.candidates.get(kind).ok_or_else(|| EngineError::Other(format!("choose: no file names the map {}", kind.id())))?;
        let pick =
            list.iter().find(|c| c.name == *file).ok_or_else(|| EngineError::Other(format!("choose: {file} is not a candidate for {}", kind.id())))?.clone();

        // The previously chosen file becomes an ignored one, the picked one stops being ignored
        if let Some(old) = set.chosen.insert(*kind, pick.clone())
            && old.name != pick.name
        {
            set.ignored.retain(|(n, _)| *n != pick.name);
            set.ignored.push((old.name, format!("another file is used for {}", kind.id())));
        }
    }
    Ok(set)
}

fn format_name(f: NormalFormat) -> &'static str {
    match f {
        NormalFormat::OpenGl => "openGl",
        NormalFormat::DirectX => "directX",
    }
}

/// The convention used for the chosen normal map.
fn normal_format_for(set: &PbrSet, forced: Option<NormalFormat>) -> NormalFormat {
    forced.or_else(|| set.chosen.get(&MapKind::Normal).and_then(|c| c.detected.normal)).unwrap_or(NormalFormat::OpenGl)
}

fn report(set: &PbrSet, forced: Option<NormalFormat>) -> Value {
    let maps: BTreeMap<&str, &str> = set.chosen.iter().map(|(k, c)| (k.id(), c.name.as_str())).collect();
    let candidates: BTreeMap<&str, Vec<&str>> =
        set.candidates.iter().filter(|(_, v)| v.len() > 1).map(|(k, v)| (k.id(), v.iter().map(|c| c.name.as_str()).collect())).collect();
    json!({
        "maps": maps,
        "candidates": candidates,
        "normalFormat": format_name(normal_format_for(set, forced)),
        "ignored": set.ignored.iter().map(|(n, why)| json!([n, why])).collect::<Vec<_>>(),
    })
}

/// A file's bytes and its decoded image.
type Loaded = (Arc<Vec<u8>>, texturecraft_formats::DecodedImage);

impl Session {
    /// Import the maps found among `files` as one fill layer on the active texture set; `load`
    /// reads a file by name. Returns the reply of `file.importPbrFolder`.
    pub fn import_pbr(&mut self, files: &FileList, load: Loader, options: &PbrOptions) -> Result<Value> {
        self.import_pbr_with_budget(files, load, options, import_memory_budget())
    }

    fn import_pbr_with_budget(&mut self, files: &FileList, load: Loader, options: &PbrOptions, memory_budget: u64) -> Result<Value> {
        let set = detect_with(files, &options.choose)?;
        if set.is_empty() {
            return Err(EngineError::Other(format!(
                "file.importPbrFolder: no PBR texture maps found among {} files (names such as albedo, roughness, metallic, normal, height, ao)",
                files.len()
            )));
        }

        let texture_set_index = self.ts();
        let available = self.doc.project.texture_set(texture_set_index).map(|t| t.channel_list()).unwrap_or_default();
        let normal_format = normal_format_for(&set, options.normal_format);
        let mut warnings: Vec<String> = Vec::new();

        // Which file feeds which channel, and how
        let mut plan: Vec<(Channel, MapKind, Take)> = Vec::new();
        let has = |k: MapKind| set.chosen.contains_key(&k);
        let direct = [
            (MapKind::BaseColor, Channel::BaseColor),
            (MapKind::Normal, Channel::Normal),
            (MapKind::Height, Channel::Height),
            (MapKind::Emissive, Channel::Emissive),
            (MapKind::Opacity, Channel::Opacity),
        ];
        for (kind, channel) in direct {
            if has(kind) {
                plan.push((channel, kind, Take::Whole));
            }
        }

        // Separate files win; a packed image fills what they leave open (R = occlusion, G = roughness, B = metallic)
        let orm = has(MapKind::PackedOrm);
        for (channel, kind, index) in
            [(Channel::AmbientOcclusion, MapKind::AmbientOcclusion, 0), (Channel::Roughness, MapKind::Roughness, 1), (Channel::Metallic, MapKind::Metallic, 2)]
        {
            if has(kind) {
                plan.push((channel, kind, Take::Whole));
            } else if channel == Channel::Roughness && has(MapKind::Glossiness) {
                plan.push((channel, MapKind::Glossiness, Take::Inverted));
            } else if orm {
                plan.push((channel, MapKind::PackedOrm, Take::Channel(index)));
            }
        }
        if orm && plan.iter().all(|(_, k, _)| *k != MapKind::PackedOrm) {
            warnings.push("the packed ORM image was not used: separate occlusion, roughness and metallic maps exist".into());
        }
        if has(MapKind::Glossiness) && has(MapKind::Roughness) {
            warnings.push("the glossiness map was not used: a roughness map exists".into());
        }

        let mut fill = Fill { projection: options.projection.clone(), ..Fill::default() };
        let mut added: Vec<(String, Arc<Vec<u8>>)> = Vec::new();
        let mut decoded = Vec::new();
        let mut channels: Vec<Channel> = Vec::new();
        let mut total_texels = 0u64;
        let mut retained_bytes = 0u64;

        // Decoded source files by name (a packed image feeds three channels)
        let mut sources: BTreeMap<String, Option<Loaded>> = BTreeMap::new();

        // Resource per (file, how) so a file used twice is stored once
        let mut made: BTreeMap<(String, Take), String> = BTreeMap::new();

        let mut uses: BTreeMap<String, usize> = BTreeMap::new();
        for (channel, kind, _) in &plan {
            if !available.contains(channel) {
                continue;
            }

            if let Some(c) = set.chosen.get(kind) {
                *uses.entry(c.name.clone()).or_default() += 1;
            }
        }

        for (channel, kind, take) in plan {
            if !available.contains(&channel) {
                warnings.push(format!("{} was skipped: this texture set has no such channel", channel.id()));
                continue;
            }

            let Some(chosen) = set.chosen.get(&kind) else { continue };
            let file = chosen.name.clone();
            let resource = if let Some(name) = made.get(&(file.clone(), take)) {
                name.clone()
            } else {
                if !sources.contains_key(&file) {
                    let output_count = uses.get(&file).copied().unwrap_or_default();
                    let allowed_texels = allowed_source_texels(memory_budget, retained_bytes, output_count).min(MAX_IMAGE_TEXELS);
                    let loaded = if allowed_texels == 0 {
                        Err("not enough memory is available to import more textures".to_string())
                    } else {
                        load(&file).and_then(|bytes| {
                            if bytes.len() as u64 > MAX_FILE_BYTES {
                                return Err(format!("the file is over {} MB", MAX_FILE_BYTES >> 20));
                            }

                            let image = texturecraft_formats::decode_image_within(&bytes, allowed_texels).map_err(|e| e.to_string())?;
                            let texels = u64::from(image.width) * u64::from(image.height);
                            total_texels = total_texels.saturating_add(texels);
                            if total_texels > MAX_TOTAL_TEXELS {
                                return Err("the textures together are too large to import".into());
                            }

                            retained_bytes = retained_bytes.saturating_add(texels.saturating_mul(RGBA_FLOAT_BYTES_PER_TEXEL * (1 + output_count as u64)));
                            Ok((Arc::new(bytes), image))
                        })
                    };
                    match loaded {
                        Ok(v) => sources.insert(file.clone(), Some(v)),
                        Err(e) => {
                            warnings.push(format!("{} was skipped: {file}: {e}", channel.id()));
                            sources.insert(file.clone(), None)
                        }
                    };
                }
                let remaining = uses.entry(file.clone()).or_default();
                *remaining = remaining.saturating_sub(1);
                let last_use = *remaining == 0;
                let leaf = file.rsplit(['/', '\\']).next().unwrap_or(&file).to_string();
                let stem = leaf.rsplit_once('.').map_or(leaf.as_str(), |(s, _)| s).to_string();
                let (resource_name, resource_bytes, resource_image) = match take {
                    Take::Whole => {
                        // The file itself; its decoded image moves into the session on its last use
                        let entry = if last_use { sources.remove(&file).flatten() } else { sources.get(&file).cloned().flatten() };
                        let Some((bytes, image)) = entry else { continue };
                        (leaf, bytes, image)
                    }
                    Take::Channel(_) | Take::Inverted => {
                        let Some(Some((_, image))) = sources.get(&file) else { continue };
                        let (c, suffix, invert) = match take {
                            Take::Channel(c) => (c, ["ao", "roughness", "metallic"].get(c).copied().unwrap_or("channel"), false),
                            _ => (0, "roughness", true),
                        };
                        let values = image.rgba.iter().map(|p| {
                            let v = p.get(c).copied().unwrap_or(0.0);
                            if invert { 1.0 - v } else { v }
                        });
                        let (png, generated_image) =
                            texturecraft_formats::gray16_resource(image.width, image.height, values).map_err(|error| EngineError::Other(error.to_string()))?;

                        if last_use {
                            sources.remove(&file);
                        }

                        (format!("{stem}_{suffix}.png"), Arc::new(png), generated_image)
                    }
                };
                let base = texturecraft_formats::sanitize_resource_name(&resource_name);
                let (mut unique, mut suffix_index) = (base.clone(), 2);
                while self.doc.resources.contains_key(&unique) || added.iter().any(|(a, _)| *a == unique) {
                    unique = format!("{suffix_index}_{base}");
                    suffix_index += 1;
                }

                added.push((unique.clone(), resource_bytes));
                decoded.push((unique.clone(), crate::resource_cmds::decoded(resource_image)));
                made.insert((file.clone(), take), unique.clone());
                unique
            };
            let source = if channel == Channel::Normal { Source::Image { name: resource, normal_format } } else { Source::image(resource) };
            fill.sources.insert(channel, source);
            channels.push(channel);
        }

        if channels.is_empty() {
            let why = if warnings.is_empty() { String::new() } else { format!(" ({})", warnings.join("; ")) };
            return Err(EngineError::Other(format!("file.importPbrFolder: nothing could be imported{why}")));
        }

        let base_name = options.name.clone().filter(|n| !n.trim().is_empty()).unwrap_or_else(|| "PBR material".to_string());
        let layer_name = self.doc.project.next_layer_name(texture_set_index, &base_name);
        let resource_names: Vec<String> = added.iter().map(|(n, _)| n.clone()).collect();
        let id = self.edit("Import PBR textures", |s| {
            for (n, bytes) in &added {
                s.doc.resources.insert(n.clone(), bytes.clone());
            }
            let id = s.doc.project.alloc_id();
            crate::layer_cmds::insert_selected(s, Layer::new(id, layer_name.clone(), LayerKind::Fill(fill), &channels))
        })?;
        self.images.extend(decoded);

        let mut reply = report(&set, options.normal_format);
        if let Some(o) = reply.as_object_mut() {
            o.insert("layer".into(), json!(id.0));
            o.insert("name".into(), json!(layer_name));
            o.insert("channels".into(), json!(channels.iter().map(|c| c.id()).collect::<Vec<_>>()));
            o.insert("resources".into(), json!(resource_names));
            o.insert("warnings".into(), json!(warnings));
        }

        Ok(reply)
    }

    /// [`Session::import_pbr`] for files already in memory (the browser, tests).
    pub fn import_pbr_bytes(&mut self, files: Vec<(String, Vec<u8>)>, options: &PbrOptions) -> Result<Value> {
        let list: FileList = files.iter().map(|(n, b)| (n.clone(), b.len() as u64)).collect();
        let by_name = std::cell::RefCell::new(files.into_iter().collect::<BTreeMap<_, _>>());

        // The importer caches each source, so ownership transfers on its only load
        let load = |name: &str| by_name.borrow_mut().remove(name).ok_or_else(|| "no such file".to_string());
        self.import_pbr(&list, &load, options)
    }
}

/// A name for the material from the files' shared leading text (`brick_wall_albedo`, `brick_wall_rough` โ†’ `brick wall`).
pub fn common_name(files: &[String]) -> Option<String> {
    let stems: Vec<&str> = files.iter().map(|f| f.rsplit(['/', '\\']).next().unwrap_or(f)).map(|l| l.rsplit_once('.').map_or(l, |(s, _)| s)).collect();
    let first = stems.first()?;
    let mut len = first.len();
    for s in &stems[1..] {
        len = first.bytes().zip(s.bytes()).take(len).take_while(|(a, b)| a.eq_ignore_ascii_case(b)).count();
    }
    let prefix = first.get(..len)?.trim_matches(|c: char| !c.is_alphanumeric());
    (prefix.chars().filter(|c| c.is_alphanumeric()).count() >= 2).then(|| prefix.replace(['_', '-'], " "))
}

// Parameters and sources (native)

fn options(cmd: &str, p: &Value) -> Result<PbrOptions> {
    let normal_format = match strp(p, "normalFormat") {
        None | Some("auto") => None,
        Some("openGl" | "opengl") => Some(NormalFormat::OpenGl),
        Some("directX" | "directx") => Some(NormalFormat::DirectX),
        Some(other) => return Err(bad(cmd, format!("unknown normal format `{other}` (auto, openGl or directX)"))),
    };

    let mut choose = BTreeMap::new();
    if let Some(obj) = p.get("choose").and_then(Value::as_object) {
        for (k, v) in obj {
            let kind = MapKind::from_id(k).ok_or_else(|| bad(cmd, format!("choose: unknown map `{k}`")))?;
            let file = v.as_str().ok_or_else(|| bad(cmd, format!("choose.{k} must be a file name")))?;
            choose.insert(kind, file.to_string());
        }
    }
    Ok(PbrOptions {
        name: strp(p, "name").filter(|name| !name.trim().is_empty()).map(str::to_string),
        normal_format,
        projection: crate::layer_cmds::projection_from(p, cmd, None)?,
        choose,
    })
}

/// Pick the one group of files that holds a material: the files at the root if they hold maps,
/// else the one folder that does. Returns the group's folder prefix (`""` or `"sub/"`).
#[cfg(not(target_arch = "wasm32"))]
fn pick_group(cmd: &str, files: &FileList) -> Result<String> {
    let mut dirs: BTreeMap<String, FileList> = BTreeMap::new();
    for (name, size) in files {
        let dir = name.rsplit_once('/').map_or("", |(d, _)| d).to_string();
        dirs.entry(dir).or_default().push((name.clone(), *size));
    }
    let with_maps: Vec<&String> = dirs.iter().filter(|(_, f)| !pbr_maps::detect(f.iter().map(|(n, s)| (n.as_str(), *s))).is_empty()).map(|(d, _)| d).collect();
    if with_maps.iter().any(|d| d.is_empty()) {
        return Ok(String::new());
    }

    match with_maps.as_slice() {
        [] => Err(bad(cmd, format!("no PBR texture maps found among {} files (names such as albedo, roughness, metallic, normal, height, ao)", files.len()))),
        [one] => Ok(format!("{one}/")),
        many => {
            let shown: Vec<&str> = many.iter().take(8).map(|d| d.as_str()).collect();
            Err(bad(
                cmd,
                format!("{} folders hold PBR maps ({}{}): import one of them", many.len(), shown.join(", "), if many.len() > 8 { ", ..." } else { "" }),
            ))
        }
    }
}

#[cfg(not(target_arch = "wasm32"))]
mod native;
#[cfg(not(target_arch = "wasm32"))]
fn import(s: &mut Session, p: &Value) -> Result<Value> {
    let cmd = "file.importPbrFolder";
    let mut options = options(cmd, p)?;
    let found = native::find(cmd, p)?;
    if options.name.is_none() {
        options.name = found.name.clone();
    }
    s.import_pbr(&found.files, &|name| found.load(name), &options)
}

#[cfg(not(target_arch = "wasm32"))]
fn scan(s: &mut Session, p: &Value) -> Result<Value> {
    let cmd = "file.scanPbrFolder";
    let options = options(cmd, p)?;
    let found = native::find(cmd, p)?;
    let set = detect_with(&found.files, &options.choose)?;
    let mut reply = report(&set, options.normal_format);
    if let Some(o) = reply.as_object_mut() {
        o.insert("name".into(), json!(options.name.or(found.name)));
        o.insert(
            "channelsAvailable".into(),
            json!(s.doc.project.texture_set(s.ts()).map(|t| t.channel_list()).unwrap_or_default().iter().map(|c| c.id()).collect::<Vec<_>>()),
        );
    }
    Ok(reply)
}

#[cfg(target_arch = "wasm32")]
fn import(_: &mut Session, p: &Value) -> Result<Value> {
    let _ = options("file.importPbrFolder", p)?;
    Err(EngineError::Other("file paths are not available in the browser".into()))
}

#[cfg(target_arch = "wasm32")]
fn scan(_: &mut Session, _: &Value) -> Result<Value> {
    Err(EngineError::Other("file paths are not available in the browser".into()))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn import_rejects_an_image_before_decoding_when_memory_is_insufficient() {
        let bytes = texturecraft_formats::gray16_png(2, 2, [0.5; 4].into_iter()).unwrap();
        let files = vec![("tile_albedo.png".to_string(), bytes.len() as u64)];
        let mut session = Session::new_project("test", crate::geom::primitives::builtin("plane").unwrap(), "builtin:plane", None, 128).unwrap();
        let load = |_: &str| Ok(bytes.clone());

        let result = session.import_pbr_with_budget(&files, &load, &PbrOptions::default(), 64);

        assert!(result.unwrap_err().to_string().contains("more than 1 texels"));
        assert!(session.doc.resources.is_empty());
        assert_eq!(allowed_source_texels(64, 0, 1), 1);
        assert_eq!(allowed_source_texels(256, 0, 1), 4);
        assert_eq!(allowed_source_texels(256, 64, 3), 2);

        let never_load = |_: &str| -> std::result::Result<Vec<u8>, String> { panic!("no source should load after the budget is spent") };
        let result = session.import_pbr_with_budget(&files, &never_load, &PbrOptions::default(), 0);

        assert!(result.unwrap_err().to_string().contains("not enough memory"));
    }
}