craft-mesh: read and write KHR_texture_transform (#1935)

This commit is contained in:
Ken Mantle
2026-11-16 21:29:47 -05:00
committed by GitHub
parent 738bf6fafe
commit 03181405cd
5 changed files with 156 additions and 18 deletions
+3 -3
View File
@@ -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,
+47 -9
View File
@@ -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<TextureRef> {
@@ -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<Value>| {
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")) }
}
+46
View File
@@ -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<UvTransform>,
}
/// 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<H: std::hash::Hasher>(&self, state: &mut H) {
self.bits().hash(state);
}
}
/// A metallic-roughness material: the simple parameters every format here can carry.
+59 -5
View File
@@ -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();
+1 -1
View File
@@ -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,
};