From 03181405cd85afddb7781c00a2025332f5c8f475 Mon Sep 17 00:00:00 2001 From: Ken Mantle Date: Mon, 16 Nov 2026 21:29:47 -0500 Subject: [PATCH] craft-mesh: read and write KHR_texture_transform (#1935) --- crates/mesh/README.md | 6 ++-- crates/mesh/src/gltf.rs | 56 +++++++++++++++++++++++++----- crates/mesh/src/lib.rs | 46 +++++++++++++++++++++++++ crates/mesh/src/tests/gltf.rs | 64 ++++++++++++++++++++++++++++++++--- crates/mesh/src/threemf.rs | 2 +- 5 files changed, 156 insertions(+), 18 deletions(-) diff --git a/crates/mesh/README.md b/crates/mesh/README.md index 3b57208fa..d58dd9072 100644 --- a/crates/mesh/README.md +++ b/crates/mesh/README.md @@ -77,13 +77,13 @@ point cloud (positions, no parts). `TRIANGLE_FAN`, indexed or not; POSITION, NORMAL, every TEXCOORD_n (up to 8), COLOR_0, JOINTS_0, WEIGHTS_0 in any component type the specification or `KHR_mesh_quantization` allows; strided buffer views; accessors without a buffer view (zeros); sparse accessors; materials with their -texture slots, UV set and sampler wrap modes, `KHR_materials_emissive_strength`, +texture slots, UV set, sampler wrap modes and `KHR_texture_transform`, `KHR_materials_emissive_strength`, `KHR_materials_unlit`, `KHR_materials_pbrSpecularGlossiness` (diffuse colour and texture, no metal, roughness from the glossiness); textures whose image is in `EXT_texture_webp`; images embedded in a buffer view or a `data:` URI, or named; skins; translation, rotation and scale animations; cameras; `KHR_lights_punctual`. Primitives of a mesh that name the same accessors share their -vertices. `write_glb` writes nodes, meshes (positions, normals, UV sets, colours), materials and -images. +vertices. `write_glb` writes nodes, meshes (positions, normals, UV sets, colours), materials with +their texture transforms, and images. The other formats' writers do not write texture transforms. **3MF.** The package is opened with `craft-opc` and the model part found through its `3dmodel` relationship; `threemf::read_model_part` reads a model part's XML on its own. Mesh objects, diff --git a/crates/mesh/src/gltf.rs b/crates/mesh/src/gltf.rs index 13e53aca1..c92051b84 100644 --- a/crates/mesh/src/gltf.rs +++ b/crates/mesh/src/gltf.rs @@ -5,8 +5,8 @@ //! primitives (`TRIANGLES`, `TRIANGLE_STRIP`, `TRIANGLE_FAN`, indexed or not) with POSITION, //! NORMAL, TANGENT, every TEXCOORD_n, COLOR_0, JOINTS_0 and WEIGHTS_0 of any component type the //! specification or `KHR_mesh_quantization` allows, strided buffer views, sparse accessors, -//! metallic-roughness materials (factors, the five texture slots with their UV set and wrap -//! modes, alpha modes, double-sided, `KHR_materials_emissive_strength`, `KHR_materials_unlit`; +//! metallic-roughness materials (factors, the five texture slots with their UV set, wrap +//! modes and `KHR_texture_transform`, alpha modes, double-sided, `KHR_materials_emissive_strength`, `KHR_materials_unlit`; //! `KHR_materials_pbrSpecularGlossiness` as its diffuse colour and texture with roughness from //! the glossiness), textures whose image is only in `EXT_texture_webp`, images (embedded //! in a buffer view or a `data:` URI, or named), skins, animations of translation, rotation @@ -36,10 +36,11 @@ use serde_json::{Map, Value, json}; use crate::{ AlphaMode, Animation, Camera, Channel, ChannelPath, Corner, Error, IDENTITY, Image, Interpolation, Light, LightKind, Limits, Material, Mesh, - NONE, Node, Part, Projection, Resolver, Result, Scene, Skin, TextureRef, Trs, Wrap, count_warning, malformed, too_large, + NONE, Node, Part, Projection, Resolver, Result, Scene, Skin, TextureRef, Trs, UvTransform, Wrap, count_warning, malformed, too_large, }; const KIND: &str = "glTF"; +const TEXTURE_TRANSFORM: &str = "KHR_texture_transform"; const CHUNK_JSON: u32 = 0x4E4F_534A; const CHUNK_BIN: u32 = 0x004E_4942; /// Most UV sets read from one primitive. @@ -583,7 +584,7 @@ fn materials(j: &Value, limits: &Limits, scene: &mut Scene) -> Result<()> { let sampler = idx(texture, "sampler").and_then(|s| arr(j, "samplers").get(s)); let webp = || texture.get("extensions").and_then(|e| e.get("EXT_texture_webp")).and_then(|e| idx(e, "source")); let image = idx(texture, "source").or_else(webp).filter(|i| *i < images)?; - Some(TextureRef { image, uv_set: 0, wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")] }) + Some(TextureRef { image, wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")], ..TextureRef::default() }) }) .collect(); let tref = |v: Option<&Value>| -> Option { @@ -593,7 +594,15 @@ fn materials(j: &Value, limits: &Limits, scene: &mut Scene) -> Result<()> { // `EXT_texture_webp`: the image when the texture has no fallback `source`. let webp = || texture.get("extensions").and_then(|e| e.get("EXT_texture_webp")).and_then(|e| idx(e, "source")); let image = idx(texture, "source").or_else(webp).filter(|i| *i < images)?; - Some(TextureRef { image, uv_set: idx(v, "texCoord").unwrap_or(0) as u32, wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")] }) + let tt = v.get("extensions").and_then(|e| e.get("KHR_texture_transform")); + // The extension's own `texCoord` overrides the texture info's. + let uv_set = tt.and_then(|t| idx(t, "texCoord")).or_else(|| idx(v, "texCoord")).unwrap_or(0); + Some(TextureRef { + image, + uv_set: u32::try_from(uv_set).unwrap_or(u32::MAX), + wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")], + transform: tt.map(uv_transform), + }) }; for m in list { let null = Value::Null; @@ -780,11 +789,25 @@ fn cameras_and_lights(j: &Value, limits: &Limits, scene: &mut Scene) -> Result<( Ok(()) } +/// A `KHR_texture_transform` object; a missing or unusable member keeps its default. +fn uv_transform(t: &Value) -> UvTransform { + let finite = |v: f64, default: f32| Some(v as f32).filter(|v| v.is_finite()).unwrap_or(default); + let d = UvTransform::default(); + let [ou, ov] = nums(t, "offset", [0.0; 2]); + let [su, sv] = nums(t, "scale", [1.0; 2]); + UvTransform { + offset: [finite(ou, d.offset[0]), finite(ov, d.offset[1])], + rotation: finite(num(t, "rotation", 0.0), d.rotation), + scale: [finite(su, d.scale[0]), finite(sv, d.scale[1])], + } +} + /// Required extensions that only change how a file looks (textures, material models) or that /// the reader handles: the geometry reads without the others being understood. fn check_extensions(j: &Value, scene: &mut Scene) -> Result<()> { - const LOOKS: [&str; 4] = ["KHR_texture_transform", "KHR_texture_basisu", "MSFT_texture_dds", "KHR_lights_punctual"]; - const READ: [&str; 5] = [ + const LOOKS: [&str; 3] = ["KHR_texture_basisu", "MSFT_texture_dds", "KHR_lights_punctual"]; + const READ: [&str; 6] = [ + TEXTURE_TRANSFORM, "KHR_mesh_quantization", "KHR_materials_unlit", "KHR_materials_emissive_strength", @@ -967,7 +990,12 @@ impl Textures { self.textures.push((image, sampler)); self.textures.len() - 1 }); - Some(json!({ "index": index, "texCoord": t.uv_set })) + let mut out = json!({ "index": index, "texCoord": t.uv_set }); + if let (Some(tt), Some(o)) = (t.transform, out.as_object_mut()) { + let ext = json!({ "offset": tt.offset, "rotation": tt.rotation, "scale": tt.scale }); + o.insert("extensions".into(), json!({ TEXTURE_TRANSFORM: ext })); + } + Some(out) } } @@ -988,6 +1016,10 @@ fn material_json(m: &Material, textures: &mut Textures, extensions: &mut Vec<&'s extensions.push(name); } } + let slots = [m.base_color_texture, m.metallic_roughness_texture, m.normal_texture, m.occlusion_texture, m.emissive_texture]; + if slots.iter().flatten().any(|t| t.transform.is_some()) && !extensions.contains(&TEXTURE_TRANSFORM) { + extensions.push(TEXTURE_TRANSFORM); + } let set = |o: &mut Value, key: &str, v: Option| { if let (Some(v), Some(o)) = (v, o.as_object_mut()) { o.insert(key.into(), v); @@ -1027,7 +1059,13 @@ fn check_finite(scene: &Scene) -> Result<()> { let materials = scene.materials.iter().all(|m| { let values = [m.metallic, m.roughness, m.normal_scale, m.occlusion_strength]; let cutoff = if let AlphaMode::Mask(c) = m.alpha_mode { c } else { 0.0 }; - m.base_color.iter().chain(&m.emissive).chain(&values).all(|x| x.is_finite()) && cutoff.is_finite() + let slots = [&m.base_color_texture, &m.metallic_roughness_texture, &m.normal_texture, &m.occlusion_texture, &m.emissive_texture]; + let transforms = slots + .into_iter() + .flatten() + .filter_map(|t| t.transform) + .all(|t| t.offset.iter().chain(&t.scale).chain([&t.rotation]).all(|x| x.is_finite())); + m.base_color.iter().chain(&m.emissive).chain(&values).all(|x| x.is_finite()) && cutoff.is_finite() && transforms }); if positions && nodes && materials { Ok(()) } else { Err(malformed(KIND, "a position, transform or material value is not finite")) } } diff --git a/crates/mesh/src/lib.rs b/crates/mesh/src/lib.rs index 59870ff31..6017c8dd2 100644 --- a/crates/mesh/src/lib.rs +++ b/crates/mesh/src/lib.rs @@ -365,6 +365,52 @@ pub struct TextureRef { pub image: usize, pub uv_set: u32, pub wrap: [Wrap; 2], + /// Where the slot's UVs land before the image is looked up (glTF `KHR_texture_transform`). + pub transform: Option, +} + +/// A UV transform: scale, then rotate by `rotation` radians, then add `offset`, in the order and +/// with the signs of glTF's `KHR_texture_transform` (v runs down the image). +/// +/// Compared and hashed by bits, so [`TextureRef`] keeps `Eq` and `Hash`. +#[derive(Clone, Copy, Debug)] +pub struct UvTransform { + pub offset: [f32; 2], + pub rotation: f32, + pub scale: [f32; 2], +} + +impl Default for UvTransform { + fn default() -> Self { + Self { offset: [0.0; 2], rotation: 0.0, scale: [1.0; 2] } + } +} + +impl UvTransform { + /// The transformed coordinate. + pub fn apply(&self, [u, v]: [f32; 2]) -> [f32; 2] { + let (sin, cos) = self.rotation.sin_cos(); + let (su, sv) = (u * self.scale[0], v * self.scale[1]); + [cos * su + sin * sv + self.offset[0], cos * sv - sin * su + self.offset[1]] + } + + fn bits(&self) -> [u32; 5] { + [self.offset[0], self.offset[1], self.rotation, self.scale[0], self.scale[1]].map(f32::to_bits) + } +} + +impl PartialEq for UvTransform { + fn eq(&self, other: &Self) -> bool { + self.bits() == other.bits() + } +} + +impl Eq for UvTransform {} + +impl std::hash::Hash for UvTransform { + fn hash(&self, state: &mut H) { + self.bits().hash(state); + } } /// A metallic-roughness material: the simple parameters every format here can carry. diff --git a/crates/mesh/src/tests/gltf.rs b/crates/mesh/src/tests/gltf.rs index 13db18a87..8892fe241 100644 --- a/crates/mesh/src/tests/gltf.rs +++ b/crates/mesh/src/tests/gltf.rs @@ -4,7 +4,7 @@ use super::hammer; use crate::gltf::{MAX_UV_SETS, MAX_ZERO_COMPONENTS, base64_decode, glb_container, read, split_glb, uri_decode, write_glb}; use crate::{ AlphaMode, ChannelPath, Corner, Error, IDENTITY, Image, Interpolation, LightKind, Limits, Material, Mesh, NONE, Node, Part, Projection, Scene, - TextureRef, Wrap, face_normal, no_external, transform_point, + TextureRef, UvTransform, Wrap, face_normal, no_external, transform_point, }; /// Builds the binary chunk with its buffer views and accessors. @@ -198,7 +198,7 @@ fn embedded_and_external_resources() { (Some(&png[..]), Some("image/png"), None) ); // The texture slot keeps its UV set and wrap modes. - assert_eq!(s.materials[0].base_color_texture, Some(TextureRef { image: 0, uv_set: 1, wrap: [Wrap::Clamp, Wrap::Mirror] })); + assert_eq!(s.materials[0].base_color_texture, Some(TextureRef { image: 0, uv_set: 1, wrap: [Wrap::Clamp, Wrap::Mirror], transform: None })); // No scene in the file: every node that is nobody's child is a root. assert_eq!(s.roots, [0]); @@ -222,6 +222,44 @@ fn embedded_and_external_resources() { assert!(parse(&gltf_text("data:;base64,!!!", "x.png").0).is_err()); } +/// A one-material file whose base colour texture info is `info`. +fn texture_info(info: Value) -> Scene { + let (doc, bin) = gltf_text("", "data:image/png;base64,iVBORw0KGgo="); + let mut v: Value = serde_json::from_slice(&doc).unwrap(); + v["materials"][0]["pbrMetallicRoughness"]["baseColorTexture"] = info; + v["buffers"][0]["uri"] = json!(format!("data:application/octet-stream;base64,{}", base64(&bin))); + parse(&serde_json::to_vec(&v).unwrap()).unwrap() +} + +#[test] +fn a_texture_transform_is_read_with_its_own_uv_set() { + let t = |s: &Scene| s.materials[0].base_color_texture.unwrap(); + let ext = json!({ "offset": [0.5, 0.25], "rotation": std::f64::consts::FRAC_PI_2, "scale": [2, 3], "texCoord": 1 }); + let s = texture_info(json!({ "index": 0, "texCoord": 0, "extensions": { "KHR_texture_transform": ext } })); + assert_eq!(t(&s).uv_set, 1, "the extension's texCoord wins"); + let tt = t(&s).transform.unwrap(); + // (1, 0): scaled to (2, 0), turned to (0, -2), moved to (0.5, -1.75). + let [u, v] = tt.apply([1.0, 0.0]); + assert!((u - 0.5).abs() < 1e-6 && (v + 1.75).abs() < 1e-6, "({u}, {v})"); + // Missing or unusable members keep their defaults. + let s = texture_info(json!({ "index": 0, "texCoord": 1, "extensions": { "KHR_texture_transform": { "scale": "big", "offset": [2] } } })); + assert_eq!((t(&s).uv_set, t(&s).transform), (1, Some(UvTransform { offset: [2.0, 0.0], ..UvTransform::default() }))); + assert_eq!(texture_info(json!({ "index": 0 })).materials[0].base_color_texture.unwrap().transform, None); +} + +/// The extension's own example (offset (0, 1), a quarter turn, half scale), which draws only the +/// image's lower-left quadrant; v runs down. +#[test] +fn the_extensions_own_example_draws_the_lower_left_quadrant() { + let ext = json!({ "offset": [0, 1], "rotation": std::f64::consts::FRAC_PI_2, "scale": [0.5, 0.5] }); + let s = texture_info(json!({ "index": 0, "extensions": { "KHR_texture_transform": ext } })); + let tt = s.materials[0].base_color_texture.unwrap().transform.unwrap(); + for uv in [[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]] { + let [u, v] = tt.apply(uv); + assert!((-1e-6..=0.5 + 1e-6).contains(&u) && (0.5 - 1e-6..=1.0 + 1e-6).contains(&v), "{uv:?} to ({u}, {v})"); + } +} + #[test] fn texture_and_sampler_inventory_includes_unreferenced_entries() { let doc = serde_json::to_vec(&json!({ @@ -237,7 +275,10 @@ fn texture_and_sampler_inventory_includes_unreferenced_entries() { let scene = read(&doc, &Limits::default(), &mut |_| Some(vec![])).unwrap(); assert_eq!( scene.texture_variants, - [TextureRef { image: 0, uv_set: 0, wrap: [Wrap::Clamp, Wrap::Mirror] }, TextureRef { image: 0, uv_set: 0, wrap: [Wrap::Repeat; 2] },] + [ + TextureRef { image: 0, wrap: [Wrap::Clamp, Wrap::Mirror], ..TextureRef::default() }, + TextureRef { image: 0, wrap: [Wrap::Repeat; 2], ..TextureRef::default() }, + ] ); assert!(scene.validate().is_ok()); @@ -470,7 +511,7 @@ fn what_is_not_read_is_refused_or_named() { json!({ "extensionsRequired": ["KHR_texture_transform", "KHR_materials_clearcoat", "KHR_mesh_quantization", "KHR_materials_unlit"] }), )) .unwrap(); - assert_eq!(s.warnings.len(), 2); + assert_eq!(s.warnings.len(), 1, "texture transforms are read: {:?}", s.warnings); assert!(parse(b"{ not json").is_err()); assert!(parse(b"").is_err()); } @@ -687,7 +728,8 @@ fn painted() -> Scene { ], ..Mesh::default() }; - let wood = TextureRef { image: 0, uv_set: 1, wrap: [Wrap::Clamp, Wrap::Repeat] }; + let tile = UvTransform { offset: [0.25, -1.5], rotation: 0.5, scale: [2.0, 4.0] }; + let wood = TextureRef { image: 0, uv_set: 1, wrap: [Wrap::Clamp, Wrap::Repeat], transform: Some(tile) }; let materials = vec![ Material { name: "Wood".into(), @@ -727,6 +769,14 @@ fn written_files_read_back() { let back = parse(&glb).unwrap(); back.validate().unwrap(); assert!(back.warnings.is_empty(), "{:?}", back.warnings); + let uses_transform = |glb: &[u8]| { + let used: Value = serde_json::from_slice(split_glb(glb).unwrap().0).unwrap(); + used["extensionsUsed"].as_array().map_or(0, |a| a.iter().filter(|e| *e == "KHR_texture_transform").count()) + }; + assert_eq!(uses_transform(&glb), 1); + let mut plain = painted(); + plain.materials.iter_mut().filter_map(|m| m.base_color_texture.as_mut()).for_each(|t| t.transform = None); + assert_eq!(uses_transform(&write_glb(&plain, &Limits::default()).unwrap()), 0, "listed only when used"); // The hierarchy: names, placement, and the mesh without triangles gone from its node. assert_eq!(back.roots, [2]); assert_eq!( @@ -764,6 +814,10 @@ fn writer_refuses_what_is_not_gltf() { s.materials[0].roughness = f32::NAN; assert!(write_glb(&s, &limits).is_err()); let mut s = painted(); + let t = s.materials.iter_mut().find_map(|m| m.base_color_texture.as_mut().and_then(|t| t.transform.as_mut())).unwrap(); + t.rotation = f32::NAN; + assert!(write_glb(&s, &limits).is_err(), "a texture transform that is not finite"); + let mut s = painted(); s.meshes[0].parts[0].corners[0].position = 50; assert!(write_glb(&s, &limits).is_err()); let mut s = painted(); diff --git a/crates/mesh/src/threemf.rs b/crates/mesh/src/threemf.rs index 50afc5b7e..a8c0abc97 100644 --- a/crates/mesh/src/threemf.rs +++ b/crates/mesh/src/threemf.rs @@ -365,7 +365,7 @@ impl Build<'_, '_> { .ok_or_else(|| too_large(KIND, format!("textures of more than {} bytes", self.limits.max_data_bytes)))?; self.scene.external.push(t.path.clone()); self.scene.images.push(Image { name: String::new(), uri: Some(t.path.clone()), mime_type: t.content_type.clone(), data }); - Some(TextureRef { image: self.scene.images.len() - 1, uv_set: 0, wrap: t.wrap }) + Some(TextureRef { image: self.scene.images.len() - 1, wrap: t.wrap, ..TextureRef::default() }) } None => None, };