From ae211ff5901981189ad2ce9bb30a797fe3255b9e Mon Sep 17 00:00:00 2001 From: SteamSmith <341182916+SteamSmith@users.noreply.github.com> Date: Sun, 1 Nov 2026 15:09:02 -0500 Subject: [PATCH] feat(export): MaterialX (.mtlx) OpenPBR material per texture set file.exportTextures takes `materialX: true` and, next to the textures, writes one `_.mtlx` per texture set: an open_pbr_surface whose inputs read tiledimage nodes, inside a surfacematerial. It follows the "OpenPBR (separate maps)" preset's inputs (base, metalness, roughness, anisotropy, coat, fuzz, transmission, subsurface, emission, opacity, normal through a normalmap node, height as a displacement shader). Colour maps are tagged srgb_texture; data maps are linear. UDIM sets use the filename token. A set with no OpenPBR map, or DirectX normals (the normalmap node reads OpenGL), is reported in `warnings`. Written from the ASWF MaterialX 1.39 and OpenPBR Surface specifications, in pure Rust with no MaterialX library. Engine tests cover a two-set export, UDIM and the off/warn paths. Co-Authored-By: Claude Sonnet 5.5 --- ROADMAP.md | 2 +- crates/engine/src/file_cmds.rs | 46 +++++- crates/engine/tests/materialx.rs | 74 +++++++++ crates/formats/src/lib.rs | 2 + crates/formats/src/materialx.rs | 275 +++++++++++++++++++++++++++++++ 5 files changed, 396 insertions(+), 3 deletions(-) create mode 100644 crates/engine/tests/materialx.rs create mode 100644 crates/formats/src/materialx.rs diff --git a/ROADMAP.md b/ROADMAP.md index b739669d..6e7a41ea 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -19,7 +19,7 @@ end to end today (engine + UI + automation + tests), not what is planned. | Baking | 10 | 100% | AO, curvature (also from the normal map), thickness, world normal, position, ID, normal, height, **bent normals, opacity, color map and world-space direction**; **high-poly meshes**, cage, frontal/rear distances, average normals, **match by mesh name**; per-texture-set selection, common and per-map parameters, progress and cancel; high-poly base color textures embedded or in files beside a `.gltf`, FBX or USD layer | — | | Viewport and display | 12 | 95% | PBR with image-based lighting, 6 procedural environments or imported HDR/EXR panoramas with exposure, rotation, blur, opacity, ACES/linear tone mapping, HDR pipeline with bloom, vignette, sharpen and grain, key-light shadows, 4× MSAA plus idle temporal accumulation, channel / mesh-map / mask / UV checker views, 3D and 2D wireframes, brush cursor, axis gizmos, subsurface scattering blur, **depth of field**, saved cameras and cameras from glTF, FBX, COLLADA and USD files, displacement (also in shadows and the path tracers), **path-traced Rendering mode** (F10, on the GPU or the CPU) with environment importance sampling and an edge-aware **denoiser** | Hardware ray tracing | | Shader | 6 | 100% | Metallic/roughness and specular/glossiness PBR, **clear coat, sheen, anisotropy and subsurface scattering** (viewport and path tracer), height-to-normal, painted normals, parallax occlusion, emissive, opacity (dithered), AO intensity | — | -| Export | 8 | 92% | 10 presets (incl. Godot 4 and **OpenPBR** with every shading lobe) plus **user output templates** (per-channel packing, converted maps, JSON import/export), PNG/JPEG/TGA/TIFF/BMP/WEBP/EXR/HDR, 8/16/32-bit, padding modes, size override, OpenGL/DirectX normals, `$udim` tiles, OBJ, textured GLB (with clearcoat/sheen) and USD (with clear coat) mesh export, zip download in the browser | Sheen and anisotropy in USD (UsdPreviewSurface has no inputs for them; GLB and OpenPBR maps carry them) | +| Export | 8 | 92% | 10 presets (incl. Godot 4 and **OpenPBR** with every shading lobe) plus **user output templates** (per-channel packing, converted maps, JSON import/export), PNG/JPEG/TGA/TIFF/BMP/WEBP/EXR/HDR, 8/16/32-bit, padding modes, size override, OpenGL/DirectX normals, `$udim` tiles, **MaterialX** (`file.exportTextures` with `materialX`: a `.mtlx` OpenPBR material per set, `` aware), OBJ, textured GLB (with clearcoat/sheen) and USD (with clear coat) mesh export, zip download in the browser | Sheen and anisotropy in USD (UsdPreviewSurface has no inputs for them; GLB and OpenPBR maps carry them) | | UI and UX | 8 | 95% | Painter-style layout with **dockable, tabbed, floating panels**, menus, tool shelf, tool bar, asset shelf, texture set list, layer stack with context menu, properties, display/shader/history/log panels, export dialog, new project dialog, bake mode, rendering mode, settings (interface scale, autosave, viewport texture resolution, system title bar), **own title bar** with the app icon and window buttons (Windows, GNOME; integrated with the macOS traffic lights), saved UI layouts, **shortcut editor** with conflict detection, tooltips with shortcuts; all menu items live ([docs/parity.md](docs/parity.md)); **9 UI languages** with CJK fonts ([docs/localization-parity.md](docs/localization-parity.md)); closed panels reopen where they were; frame-budgeted compositing and uploads keep 8K sets responsive | Native-speaker review of the translations | | Platforms | 4 | 75% | Windows, macOS (universal, signed and notarized), Linux (AppImage, deb, rpm, tar.gz, Flatpak), FreeBSD and web release workflows | First real release run; web build polish | | **Total** | **100** | **≈ 93%** | | | diff --git a/crates/engine/src/file_cmds.rs b/crates/engine/src/file_cmds.rs index 32ae6b49..f489582c 100644 --- a/crates/engine/src/file_cmds.rs +++ b/crates/engine/src/file_cmds.rs @@ -42,7 +42,7 @@ pub fn specs() -> Vec { "Export textures", ["File"], None, - "{dir, preset?: built-in or user preset name, or a preset object {name, maps}, ts?: index|\"all\", format?: png|jpg|tga|tif|exr|..., bitDepth?, padding?: none|dilation|dilationDefault|infinite, dilation?: px, size?: px, normalFormat?: openGl|directX}", + "{dir, preset?: built-in or user preset name, or a preset object {name, maps}, ts?: index|\"all\", format?: png|jpg|tga|tif|exr|..., bitDepth?, padding?: none|dilation|dilationDefault|infinite, dilation?: px, size?: px, normalFormat?: openGl|directX, materialX?: bool (also write a .mtlx OpenPBR material per texture set; needs the \"OpenPBR (separate maps)\" preset)} → {files, warnings}", always, export_textures ), @@ -418,11 +418,53 @@ fn export_textures(s: &mut Session, p: &Value) -> Result { std::fs::create_dir_all(&dir).map_err(|e| bad("file.exportTextures", format!("cannot create {dir}: {e}")))?; let files = s.export_files(&sets, &opts)?; let warnings: Vec = files.iter().flat_map(|f| f.warnings.iter().cloned()).collect(); - let written = texturecraft_formats::write_files(&files, std::path::Path::new(&dir)).map_err(fe)?; + let mut warnings = warnings; + let mut written = texturecraft_formats::write_files(&files, std::path::Path::new(&dir)).map_err(fe)?; + if p.get("materialX").and_then(Value::as_bool).unwrap_or(false) { + written.extend(write_materialx(s, &sets, &opts, std::path::Path::new(&dir), &mut warnings)?); + } s.log.push(format!("Exported {} textures to {dir}", written.len())); Ok(json!({ "files": written.iter().map(|p| p.display().to_string()).collect::>(), "warnings": warnings })) } +/// One `_.mtlx` per texture set, next to the textures `opts` just wrote: the +/// OpenPBR inputs those textures feed (see `texturecraft_formats::materialx`). UDIM sets name +/// their files with the `` token. Sets with no recognised map are skipped with a warning. +#[cfg(not(target_arch = "wasm32"))] +fn write_materialx(s: &Session, sets: &[usize], opts: &ExportOptions, dir: &std::path::Path, warnings: &mut Vec) -> Result> { + use texturecraft_formats::materialx::{self, Texture}; + let mesh_name = stem_of(s.doc.project.mesh.trim_start_matches("builtin:")); + if opts.normal_format == Some(NormalFormat::DirectX) { + warnings.push("MaterialX: the normalmap node reads OpenGL (+Y) normals; this export wrote DirectX normals, so flip the green channel".into()); + } + let mut out = Vec::new(); + for &ts in sets { + let set = s.doc.project.texture_set(ts).map_err(|e| EngineError::Other(e.to_string()))?; + let mut textures: Vec = Vec::new(); + for f in texturecraft_formats::list_outputs(&s.doc.project, ts, &mesh_name, opts).map_err(fe)? { + let Some(input) = opts.preset.maps.get(f.map).and_then(|m| materialx::input_of_template(&m.file)) else { continue }; + // The first tile stands for all of them: 1001 -> . + let file = match f.tile { + Some(t) => f.name.replacen(&format!(".{t}."), "..", 1), + None => f.name.clone(), + }; + if !textures.iter().any(|t| t.input == input) { + textures.push(Texture { input: input.to_owned(), file }); + } + } + if textures.is_empty() { + warnings.push(format!("MaterialX: texture set \"{}\" has no OpenPBR maps; use the \"OpenPBR (separate maps)\" preset", set.name)); + continue; + } + let stem = texturecraft_formats::export::sanitize_file_stem(&format!("{mesh_name}_{}", set.name)); + let path = dir.join(format!("{stem}.mtlx")); + std::fs::write(&path, materialx::write(&format!("{mesh_name}_{}", set.name), &textures, None)) + .map_err(|e| bad("file.exportTextures", format!("cannot write {}: {e}", path.display())))?; + out.push(path); + } + Ok(out) +} + #[cfg(not(target_arch = "wasm32"))] fn export_mesh(s: &mut Session, p: &Value) -> Result { let path = native::path_param(p, "path", "file.exportMesh")?; diff --git a/crates/engine/tests/materialx.rs b/crates/engine/tests/materialx.rs new file mode 100644 index 00000000..02de5528 --- /dev/null +++ b/crates/engine/tests/materialx.rs @@ -0,0 +1,74 @@ +//! `file.exportTextures` with `materialX: true`: a `.mtlx` OpenPBR material next to the textures. + +use serde_json::{Value, json}; +use texturecraft_engine::geom::primitives; +use texturecraft_engine::{Session, execute}; + +const OPENPBR: &str = "OpenPBR (separate maps)"; + +fn temp(tag: &str) -> std::path::PathBuf { + let dir = std::env::temp_dir().join(format!("tc_mtlx_{tag}_{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + dir +} + +fn export(s: &mut Session, dir: &std::path::Path, preset: &str, mtlx: bool) -> Value { + execute(s, "file.exportTextures", &json!({"dir": dir.display().to_string(), "preset": preset, "materialX": mtlx})).unwrap() +} + +fn files(r: &Value) -> Vec { + r["files"].as_array().unwrap().iter().map(|f| f.as_str().unwrap().to_string()).collect() +} + +#[test] +fn writes_a_material_that_names_the_exported_textures() { + let mut s = Session::new_project("t", primitives::material_ball(), "builtin:material_ball", None, 128).unwrap(); + let dir = temp("ball"); + let r = export(&mut s, &dir, OPENPBR, true); + let all = files(&r); + let mtlx: Vec<&String> = all.iter().filter(|f| f.ends_with(".mtlx")).collect(); + assert_eq!(mtlx.len(), s.set_count(), "one material per texture set: {all:?}"); + for path in mtlx { + let set = path.rsplit(['/', '\\']).next().unwrap().trim_end_matches(".mtlx").to_string(); + let text = std::fs::read_to_string(path).unwrap(); + assert!(text.contains("= 3, "base colour, roughness and normal at least: {text}"); + assert!(text.contains("name=\"base_color\"") && text.contains("name=\"geometry_normal\""), "{text}"); + } + let _ = std::fs::remove_dir_all(&dir); +} + +#[test] +fn off_by_default_and_warns_without_openpbr_maps() { + let mut s = Session::new_project("t", primitives::material_ball(), "builtin:material_ball", None, 128).unwrap(); + let dir = temp("off"); + assert!(!files(&export(&mut s, &dir, OPENPBR, false)).iter().any(|f| f.ends_with(".mtlx"))); + let _ = std::fs::remove_dir_all(&dir); + let dir = temp("other"); + let r = export(&mut s, &dir, "Document channels + Normal + AO", true); + assert!(!files(&r).iter().any(|f| f.ends_with(".mtlx"))); + assert!(r["warnings"].as_array().unwrap().iter().any(|w| w.as_str().unwrap().contains("OpenPBR")), "{r}"); + let _ = std::fs::remove_dir_all(&dir); +} + +#[test] +fn udim_sets_use_the_udim_token() { + let mut s = Session::new_project("t", primitives::udim_plane(), "builtin:udim_plane", None, 128).unwrap(); + let dir = temp("udim"); + let r = export(&mut s, &dir, OPENPBR, true); + let all = files(&r); + let mtlx = all.iter().find(|f| f.ends_with(".mtlx")).unwrap_or_else(|| panic!("no .mtlx in {all:?}")); + let text = std::fs::read_to_string(mtlx).unwrap(); + assert!(text.contains(".<UDIM>.png"), "{text}"); + assert!(!text.contains(".1001.") && !text.contains(".1002."), "{text}"); + assert!(all.iter().any(|f| f.ends_with(".1001.png")) && all.iter().any(|f| f.ends_with(".1002.png"))); + let _ = std::fs::remove_dir_all(&dir); +} diff --git a/crates/formats/src/lib.rs b/crates/formats/src/lib.rs index 249ff0f7..7ddd7577 100644 --- a/crates/formats/src/lib.rs +++ b/crates/formats/src/lib.rs @@ -12,6 +12,7 @@ //! - [`export`]: texture export from a texture set's composite through [`ExportPreset`]s (file //! name templates, channel packing, virtual maps such as the final normal, padding, resizing) //! to PNG, JPEG, TGA, TIFF, BMP, WebP, EXR and HDR bytes. +//! - [`materialx`]: a MaterialX (`.mtlx`) OpenPBR document for an exported texture set. //! - [`presets`]: the built-in export presets and JSON (de)serialization of user presets. //! - [`project_file`]: the `.tcraft` project zip (project JSON, sparse lossless pixel tiles, //! baked maps, the original mesh and a thumbnail). @@ -23,6 +24,7 @@ pub mod export; pub mod image_res; +pub mod materialx; pub mod mesh_export; pub mod mesh_import; pub mod presets; diff --git a/crates/formats/src/materialx.rs b/crates/formats/src/materialx.rs new file mode 100644 index 00000000..d178f7b7 --- /dev/null +++ b/crates/formats/src/materialx.rs @@ -0,0 +1,275 @@ +//! MaterialX documents for exported texture sets, written from the ASWF MaterialX specification +//! (version 1.39) and the OpenPBR Surface specification. Pure Rust: no MaterialX library is +//! linked, and nothing is read from any other application. +//! +//! [`write`] takes a material's name and the texture files an export produced, each tagged with +//! the OpenPBR input it feeds, and gives the text of a `.mtlx` file: an `open_pbr_surface` shader +//! whose inputs read `tiledimage` nodes, wrapped in a `surfacematerial`. The inputs are the ones +//! the built-in "OpenPBR (separate maps)" export preset writes ([`INPUTS`]); `height` becomes a +//! `displacement` shader on the material and `geometry_normal` goes through a `normalmap` node +//! (OpenGL, +Y up, which is what that node expects). +//! +//! Colour textures (base, fuzz and emission colour) are tagged `srgb_texture`; every data map is +//! left untagged (linear). UDIM sets write the `` filename token MaterialX defines. +//! Texture file names are relative to the document. + +use std::collections::HashSet; +use std::fmt::Write as _; + +/// How an OpenPBR input is typed in the document. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Kind { + /// `color3` from an sRGB texture. + Color, + /// `float` from a linear texture. + Float, + /// `vector3` through a `normalmap` node. + Normal, + /// `float` driving a `displacement` shader. + Height, +} + +/// The OpenPBR inputs the export writes, in document order. Names are the file-name suffixes of +/// the built-in OpenPBR preset's maps (`$mesh_$textureSet_`). +pub const INPUTS: &[(&str, Kind)] = &[ + ("base_color", Kind::Color), + ("base_metalness", Kind::Float), + ("specular_roughness", Kind::Float), + ("specular_roughness_anisotropy", Kind::Float), + ("coat_weight", Kind::Float), + ("coat_roughness", Kind::Float), + ("fuzz_weight", Kind::Float), + ("fuzz_color", Kind::Color), + ("fuzz_roughness", Kind::Float), + ("transmission_weight", Kind::Float), + ("subsurface_weight", Kind::Float), + ("emission_color", Kind::Color), + ("geometry_opacity", Kind::Float), + ("geometry_normal", Kind::Normal), + ("height", Kind::Height), +]; + +/// The file-name prefix of the built-in OpenPBR preset's maps. +const PREFIX: &str = "$mesh_$textureSet_"; + +/// One exported texture: the OpenPBR input it feeds and the file (relative to the `.mtlx`). +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Texture { + pub input: String, + pub file: String, +} + +/// The OpenPBR input a preset map's file template feeds (`$mesh_$textureSet_base_color` → +/// `base_color`), or None for templates this module has no place for. +pub fn input_of_template(template: &str) -> Option<&'static str> { + let suffix = template.strip_prefix(PREFIX)?; + INPUTS.iter().find(|(n, _)| *n == suffix).map(|(n, _)| *n) +} + +fn kind_of(input: &str) -> Option { + INPUTS.iter().find(|(n, _)| *n == input).map(|(_, k)| *k) +} + +/// A MaterialX name: letters, digits and underscores, not starting with a digit. +pub fn node_name(s: &str) -> String { + let mut out: String = s.chars().map(|c| if c.is_ascii_alphanumeric() || c == '_' { c } else { '_' }).collect(); + if out.is_empty() || out.starts_with(|c: char| c.is_ascii_digit()) { + out.insert(0, '_'); + } + out +} + +fn esc(s: &str) -> String { + let mut out = String::with_capacity(s.len()); + for c in s.chars() { + match c { + '&' => out.push_str("&"), + '<' => out.push_str("<"), + '>' => out.push_str(">"), + '"' => out.push_str("""), + '\'' => out.push_str("'"), + c if c.is_control() => out.push(' '), + c => out.push(c), + } + } + out +} + +fn image_name(input: &str) -> String { + format!("image_{}", node_name(input)) +} + +/// The text of a MaterialX document for `name` with the given textures. `physical_size_cm` goes +/// into the material's `doc` attribute. Inputs this module has no place for are skipped, and so +/// are repeats of one input (the first wins). +pub fn write(name: &str, textures: &[Texture], physical_size_cm: Option<[f32; 2]>) -> String { + let base = node_name(name); + let mut seen = HashSet::new(); + let tex: Vec<(&Texture, Kind)> = textures.iter().filter_map(|t| kind_of(&t.input).map(|k| (t, k))).filter(|(t, _)| seen.insert(t.input.as_str())).collect(); + let has = |i: &str| tex.iter().any(|(t, _)| t.input == i); + let mut x = String::new(); + let _ = writeln!(x, ""); + let _ = writeln!(x, ""); + + let shader = format!("OPBR_{base}"); + let _ = writeln!(x, " ", esc(&shader)); + for (t, kind) in &tex { + let (ty, node) = match kind { + Kind::Color => ("color3", image_name(&t.input)), + Kind::Float => ("float", image_name(&t.input)), + Kind::Normal => ("vector3", "normalmap".to_owned()), + Kind::Height => continue, + }; + let _ = writeln!(x, " ", t.input); + } + if has("emission_color") { + let _ = writeln!(x, " "); + } + let _ = writeln!(x, " "); + + for (t, kind) in &tex { + let (ty, space) = match kind { + Kind::Color => ("color3", Some("srgb_texture")), + Kind::Normal => ("vector3", None), + Kind::Float | Kind::Height => ("float", None), + }; + let node = image_name(&t.input); + let _ = writeln!(x, " "); + match space { + Some(space) => { + let _ = writeln!(x, " ", esc(&t.file)); + } + None => { + let _ = writeln!(x, " ", esc(&t.file)); + } + } + let _ = writeln!(x, " "); + } + if has("geometry_normal") { + let _ = writeln!(x, " "); + let _ = writeln!(x, " ", image_name("geometry_normal")); + let _ = writeln!(x, " "); + } + if has("height") { + let _ = writeln!(x, " "); + let _ = writeln!(x, " ", image_name("height")); + let _ = writeln!(x, " "); + let _ = writeln!(x, " "); + } + + let doc = match physical_size_cm { + Some([w, h]) if w.is_finite() && h.is_finite() => format!(" doc=\"Tiles every {w} x {h} cm\""), + _ => String::new(), + }; + let _ = writeln!(x, " ", esc(&base)); + let _ = writeln!(x, " ", esc(&shader)); + if has("height") { + let _ = writeln!(x, " "); + } + let _ = writeln!(x, " "); + let _ = writeln!(x, ""); + x +} + +#[cfg(test)] +mod tests { + use super::*; + + fn tex(input: &str, file: &str) -> Texture { + Texture { input: input.into(), file: file.into() } + } + + /// Every start tag is closed or self-closed, in order: enough to catch a malformed writer. + fn balanced(xml: &str) -> bool { + let mut stack: Vec = Vec::new(); + let mut rest = xml; + while let Some(i) = rest.find('<') { + let Some(j) = rest.get(i..).and_then(|r| r.find('>')) else { return false }; + let Some(tag) = rest.get(i + 1..i + j) else { return false }; + rest = rest.get(i + j + 1..).unwrap_or(""); + if tag.starts_with('?') || tag.starts_with('!') { + continue; + } + if let Some(name) = tag.strip_prefix('/') { + if stack.pop().as_deref() != Some(name.trim()) { + return false; + } + } else if !tag.ends_with('/') { + stack.push(tag.split_whitespace().next().unwrap_or("").to_owned()); + } + } + stack.is_empty() + } + + #[test] + fn a_full_material_maps_every_input() { + let t: Vec = INPUTS.iter().map(|(n, _)| tex(n, &format!("stone_{n}.png"))).collect(); + let x = write("Stone", &t, Some([100.0, 50.0])); + assert!(balanced(&x), "{x}"); + for want in [ + "", + "name=\"base_color\" type=\"color3\" nodename=\"image_base_color\"", + "name=\"base_metalness\" type=\"float\" nodename=\"image_base_metalness\"", + "name=\"specular_roughness\" type=\"float\" nodename=\"image_specular_roughness\"", + "name=\"coat_weight\" type=\"float\" nodename=\"image_coat_weight\"", + "name=\"fuzz_color\" type=\"color3\" nodename=\"image_fuzz_color\"", + "name=\"transmission_weight\" type=\"float\"", + "name=\"subsurface_weight\" type=\"float\"", + "name=\"geometry_opacity\" type=\"float\" nodename=\"image_geometry_opacity\"", + "name=\"geometry_normal\" type=\"vector3\" nodename=\"normalmap\"", + "name=\"emission_color\" type=\"color3\" nodename=\"image_emission_color\"", + "name=\"emission_luminance\" type=\"float\" value=\"1\"", + "value=\"stone_base_color.png\" colorspace=\"srgb_texture\"", + "value=\"stone_emission_color.png\" colorspace=\"srgb_texture\"", + "", + "", + "name=\"displacementshader\"", + "", + ] { + assert!(x.contains(want), "missing {want}\n{x}"); + } + // Data textures carry no colour space, and height is not an OpenPBR input. + assert!(x.contains("value=\"stone_specular_roughness.png\" />")); + assert!(!x.contains("name=\"height\"")); + } + + #[test] + fn only_what_is_there_is_written() { + let x = write("m", &[tex("specular_roughness", "r.png")], None); + assert!(balanced(&x)); + assert!(!x.contains("base_color") && !x.contains("normalmap") && !x.contains("displacement") && !x.contains("emission_luminance")); + assert!(x.contains("")); + let none = write("m", &[], None); + assert!(balanced(&none) && none.contains("&\"c", &[tex("base_color", "x\"&<'>..png")], Some([f32::NAN, 1.0])); + assert!(balanced(&x.replace("<UDIM>", "UDIM")), "{x}"); + assert!(x.contains("value=\"x"&<'>.<UDIM>.png\"")); + assert!(!x.contains("doc="), "a non-finite size is left out"); + assert!(x.contains("OPBR_a_b___c")); + } +}