d84914ef1e5a
mod.rs
//! Recognising the maps of a PBR texture set from file names.
//!
//! Texture sites, scanners and game engines name the same maps in many ways (`Brick_Albedo.png`,
//! `brick_diff_4k.jpg`, `T_Brick_BC.tga`, `brick-NormalDX.exr`, `Brick_ARM.png`, `_BaseMap`...).
//! This module turns a list of file names into one [`PbrSet`]: for each [`MapKind`] the best
//! file, the other candidates, the normal-map convention and the files it ignored. It is pure
//! (names in, names out), so it works in the browser too and is tested with a table of
//! real-world styles.
//!
//! # Rules
//!
//! 1. Only image files count (`png jpg jpeg tga tif tiff bmp webp exr hdr`), matched
//! case-insensitively. Dot files (`._x.png`, made by archivers on a Mac), files in
//! `__MACOSX` and preview images (a token such as `preview`, `thumb`, `thumbnail`, `sphere`,
//! `render`, `swatch`, `icon`, `screenshot`) are ignored.
//! 2. The file stem is split into lower-case tokens at separators (`_ - . space`), at
//! lower→upper case changes (`BaseColor`) and between letters and digits (`diff4k`).
//! 3. The map is named by the **last** known word (or word pair); resolution (`1k`..`16k`,
//! `2048`), bit depth (`16bit`), convention (`gl`, `dx`) and other tokens are skipped.
//! Pairs (`base color`, `ambient occlusion`, `ao rough metal`) and glued names
//! (`basecolor`, `normaldx`) are understood.
//! 4. Normal maps: `gl` / `ogl` / `opengl` means OpenGL, `dx` / `d3d` / `directx` means DirectX;
//! with neither the convention is unknown and the caller's default applies.
//! 5. When several files name the same map the best wins: for normals the OpenGL one (no
//! flip), then the highest resolution token, then the largest file, then the name. All of
//! them stay in [`PbrSet::candidates`] so a caller can ask the user.
//!
//! Single letters are not accepted, except a trailing `n` (normal): `r`, `m`, `d` and `h` are
//! ambiguous with colour channels.
use texturecraft_core::NormalFormat;
mod candidate;
mod detected;
mod map_kind;
mod pbr_set;
pub use candidate::Candidate;
pub use detected::Detected;
pub use map_kind::MapKind;
pub use pbr_set::PbrSet;
/// File extensions read as images (lower case).
pub const IMAGE_EXTS: &[&str] = &["png", "jpg", "jpeg", "tga", "tif", "tiff", "bmp", "webp", "exr", "hdr"];
// Tokens
/// Lower-case tokens of a file stem: split at separators, camelCase changes and letter/digit
/// changes; a number and its unit stay together (`4k`, `16bit`).
fn tokens(stem: &str) -> Vec<String> {
let chars: Vec<char> = stem.chars().collect();
let mut out: Vec<String> = Vec::new();
let mut current_token = String::new();
let mut previous_char: Option<char> = None;
for (i, &c) in chars.iter().enumerate() {
if !c.is_alphanumeric() {
if !current_token.is_empty() {
out.push(std::mem::take(&mut current_token));
}
previous_char = None;
continue;
}
if let Some(p) = previous_char {
let next_lower = chars.get(i + 1).is_some_and(|n| n.is_lowercase());
// aB -> a|B; ABc -> A|Bc; a1 -> a|1; 1a -> 1|a
let split =
(p.is_lowercase() && c.is_uppercase()) || (p.is_uppercase() && c.is_uppercase() && next_lower) || (p.is_alphabetic() != c.is_alphabetic());
if split && !current_token.is_empty() {
out.push(std::mem::take(&mut current_token));
}
}
current_token.extend(c.to_lowercase());
previous_char = Some(c);
}
if !current_token.is_empty() {
out.push(current_token);
}
let mut joined: Vec<String> = Vec::new();
for t in out {
if let Some(last) = joined.last_mut()
&& !last.is_empty()
&& last.chars().all(|c| c.is_ascii_digit())
&& matches!(t.as_str(), "k" | "bit" | "px")
{
last.push_str(&t);
continue;
}
joined.push(t);
}
joined
}
/// Pixels named by a resolution token: `1k`..`16k`, `512px`, or a bare power of two ≥ 128.
fn resolution_of(t: &str) -> Option<u32> {
if let Some(n) = t.strip_suffix('k').and_then(|n| n.parse::<u32>().ok()) {
return (1..=16).contains(&n).then(|| n * 1024);
}
if let Some(n) = t.strip_suffix("px").and_then(|n| n.parse::<u32>().ok()) {
return (16..=16384).contains(&n).then_some(n);
}
let n: u32 = t.parse().ok()?;
((128..=16384).contains(&n) && n.is_power_of_two()).then_some(n)
}
fn normal_format_of(t: &str) -> Option<NormalFormat> {
match t {
"gl" | "ogl" | "opengl" | "normalgl" => Some(NormalFormat::OpenGl),
"dx" | "d3d" | "directx" | "normaldx" => Some(NormalFormat::DirectX),
_ => None,
}
}
/// A single known word → (kind, strength).
fn word(t: &str) -> Option<(MapKind, u8)> {
use MapKind::*;
Some(match t {
"basecolor" | "basecolour" | "albedo" | "diffuse" | "diff" | "dif" | "col" | "color" | "colour" | "bc" | "basemap" | "maintex" | "alb" => {
(BaseColor, 3)
}
"roughness" | "rough" | "rgh" | "rou" => (Roughness, 3),
"gloss" | "glossiness" | "glossy" | "smoothness" | "smooth" => (Glossiness, 3),
"metallic" | "metalness" | "metal" | "mtl" | "met" => (Metallic, 3),
"normal" | "nrm" | "nor" | "norm" | "nrml" | "normalmap" | "bumpmap" | "nm" | "n" | "normalgl" | "normaldx" => (Normal, 3),
"height" | "disp" | "displacement" | "displace" | "heightmap" | "hgt" | "dsp" | "parallax" => (Height, 3),
"bump" => (Height, 1),
"ao" | "ambientocclusion" | "occlusion" | "occ" | "ambocc" | "occlusionmap" => (AmbientOcclusion, 3),
"emissive" | "emission" | "emit" | "emis" | "glow" | "emissivecolor" | "emissionmap" | "illum" => (Emissive, 3),
"opacity" | "alpha" | "opac" | "transparency" | "cutout" | "coverage" => (Opacity, 3),
"orm" | "arm" | "aorm" => (PackedOrm, 4),
"cavity" | "curvature" | "specular" | "spec" | "translucency" | "thickness" | "scatter" | "sss" | "fuzz" | "sheen" | "ior" | "mask" | "flow"
| "reflection" => (Unused, 1),
_ => return None,
})
}
fn is_preview(t: &str) -> bool {
matches!(t, "preview" | "previews" | "thumb" | "thumbs" | "thumbnail" | "sphere" | "render" | "swatch" | "icon" | "screenshot" | "prev" | "overview")
}
fn is_junk_path(path: &str) -> bool {
path.split(['/', '\\']).any(|part| part == "__MACOSX" || part.starts_with("._") || part == ".DS_Store")
}
/// What the file `name` (a path or a bare name) is, or why it is not a map.
pub fn classify(name: &str) -> std::result::Result<Detected, &'static str> {
if is_junk_path(name) {
return Err("hidden or archive metadata file");
}
let leaf = name.rsplit(['/', '\\']).next().unwrap_or(name);
let (stem, ext) = leaf.rsplit_once('.').unwrap_or((leaf, ""));
if !IMAGE_EXTS.contains(&ext.to_ascii_lowercase().as_str()) {
return Err("not an image");
}
let name_tokens = tokens(stem);
if name_tokens.iter().any(|t| is_preview(t)) {
return Err("preview image");
}
let resolution = name_tokens.iter().filter_map(|t| resolution_of(t)).max().unwrap_or(0);
let normal = name_tokens.iter().enumerate().find_map(|(i, t)| {
normal_format_of(t).or_else(|| match (t.as_str(), name_tokens.get(i + 1).map(String::as_str), name_tokens.get(i + 2).map(String::as_str)) {
("direct", Some("x"), _) | ("d", Some("3"), Some("d")) => Some(NormalFormat::DirectX),
("open", Some("gl"), _) => Some(NormalFormat::OpenGl),
_ => None,
})
});
// (token index, kind, strength) of every known word
let words: Vec<(usize, MapKind, u8)> = name_tokens.iter().enumerate().filter_map(|(i, t)| word(t).map(|(k, s)| (i, k, s))).collect();
let done = |kind: MapKind, strength: u8| Ok(Detected { kind, normal: if kind == MapKind::Normal { normal } else { None }, resolution, strength });
// `ao rough metal` written as three words competes with later map names
let mut packed_end = None;
for w in words.windows(3) {
if let [(a, MapKind::AmbientOcclusion, _), (b, MapKind::Roughness, _), (c, MapKind::Metallic, _)] = w
&& *b == a + 1
&& *c == b + 1
{
packed_end = Some(*c);
}
}
// Word pairs and the position they end at
let mut pair: Option<(usize, MapKind)> = None;
for (i, t) in name_tokens.iter().enumerate() {
let next = name_tokens.get(i + 1).map(String::as_str);
let kind = match (t.as_str(), next) {
("base", Some("color" | "colour" | "map")) | ("main", Some("tex")) => Some(MapKind::BaseColor),
("emissive", Some("color" | "colour")) => Some(MapKind::Emissive),
("ambient", Some("occlusion")) | ("mixed", Some("ao")) => Some(MapKind::AmbientOcclusion),
("bump", Some("map")) => Some(MapKind::Normal),
_ => None,
};
if let Some(kind) = kind {
pair = Some((i + 1, kind));
}
}
// The last known word wins; a pair counts if it ends at or after it
let single = words.iter().rev().find(|(i, kind, _)| {
// A lone `n` only names a normal map as the final meaningful token
let lone_n = name_tokens.get(*i).is_some_and(|t| t == "n");
!lone_n
|| (*kind == MapKind::Normal
&& name_tokens.iter().skip(i + 1).all(|t| resolution_of(t).is_some() || normal_format_of(t).is_some() || t.ends_with("bit")))
});
if packed_end.is_some_and(|end| pair.is_none_or(|(index, _)| end >= index) && single.is_none_or(|(index, _, _)| end >= *index)) {
return done(MapKind::PackedOrm, 4);
}
match (pair, single) {
(Some((pair_index, kind)), Some((single_index, _, _))) if pair_index >= *single_index => done(kind, 3),
(Some((_, kind)), None) => done(kind, 3),
(_, Some((_, MapKind::Height, 1))) => {
// `bump` is weak: any stronger word in the name wins over it
match words.iter().rev().find(|(_, k, s)| *s >= 3 && *k != MapKind::Unused) {
Some((_, k, s)) => done(*k, *s),
None => done(MapKind::Height, 1),
}
}
(_, Some((_, kind, strength))) => done(*kind, *strength),
(None, None) => Err("unknown map name"),
}
}
/// Sort key for files naming the same map: smaller is better.
type Rank = (u8, std::cmp::Reverse<u8>, std::cmp::Reverse<u32>, std::cmp::Reverse<u64>, String);
fn rank(c: &Candidate) -> Rank {
// OpenGL first (no flip), then unlabelled, then DirectX
let format_priority = match c.detected.normal {
Some(NormalFormat::OpenGl) => 0,
None => 1,
Some(NormalFormat::DirectX) => 2,
};
(format_priority, std::cmp::Reverse(c.detected.strength), std::cmp::Reverse(c.detected.resolution), std::cmp::Reverse(c.bytes), c.name.to_ascii_lowercase())
}
/// Group `files` (`(path, size in bytes)`) into a [`PbrSet`].
pub fn detect<'a>(files: impl IntoIterator<Item = (&'a str, u64)>) -> PbrSet {
let mut set = PbrSet::default();
for (name, bytes) in files {
match classify(name) {
Err(why) => set.ignored.push((name.to_string(), why.to_string())),
Ok(d) if d.kind == MapKind::Unused => set.ignored.push((name.to_string(), "unused map".to_string())),
Ok(detected) => set.candidates.entry(detected.kind).or_default().push(Candidate { name: name.to_string(), detected, bytes }),
}
}
for (kind, list) in &mut set.candidates {
list.sort_by_key(rank);
if let Some(best) = list.first() {
set.chosen.insert(*kind, best.clone());
}
for other in list.iter().skip(1) {
set.ignored.push((other.name.clone(), format!("another file is used for {}", kind.id())));
}
}
set
}
#[cfg(test)]
mod tests {
use super::*;
use MapKind::*;
fn kind(name: &str) -> Option<MapKind> {
classify(name).ok().map(|d| d.kind)
}
#[test]
fn emissive_color_alias_survives_camel_case() {
assert_eq!(kind("brick_emissivecolor.png"), Some(Emissive));
assert_eq!(kind("brick_EmissiveColor.png"), Some(Emissive));
}
#[test]
fn real_world_naming_styles() {
let table: &[(&str, MapKind)] = &[
// Plain suffixes, any case and separator
("brick_albedo.png", BaseColor),
("brick_basecolor.png", BaseColor),
("brick_base_color.png", BaseColor),
("Brick_BaseColor.png", BaseColor),
("Brick-Base-Color.PNG", BaseColor),
("brick_diffuse.jpg", BaseColor),
("brick_diff_4k.jpg", BaseColor),
("brick_col.tga", BaseColor),
("brick_color.png", BaseColor),
("Brick_Colour.png", BaseColor),
("brick_roughness.png", Roughness),
("brick_rough.png", Roughness),
("brick_Rough_2K.jpg", Roughness),
("brick_metallic.png", Metallic),
("brick_metalness.png", Metallic),
("brick_metal.png", Metallic),
("brick_normal.png", Normal),
("brick_nrm.png", Normal),
("brick_nor_gl_4k.exr", Normal),
("brick_nor_dx_4k.exr", Normal),
("brick_NormalGL.jpg", Normal),
("brick_NormalDX.jpg", Normal),
("brick_normal_opengl.png", Normal),
("brick_n.png", Normal),
("brick_n_2k.png", Normal),
("brick_height.png", Height),
("brick_disp_4k.png", Height),
("brick_displacement.png", Height),
("brick_Displacement.jpg", Height),
("brick_ao.png", AmbientOcclusion),
("brick_AO.png", AmbientOcclusion),
("brick_ambientocclusion.png", AmbientOcclusion),
("brick_AmbientOcclusion.jpg", AmbientOcclusion),
("brick_ambient_occlusion.png", AmbientOcclusion),
("brick_occlusion.png", AmbientOcclusion),
("brick_mixed_ao.png", AmbientOcclusion),
("brick_emissive.png", Emissive),
("brick_emission.png", Emissive),
("brick_opacity.png", Opacity),
("brick_alpha.png", Opacity),
("brick_orm.png", PackedOrm),
("brick_arm_2k.jpg", PackedOrm),
("brick_ao_rough_metal.png", PackedOrm),
// Prefix styles and engine conventions
("Albedo_brick.png", BaseColor),
("T_Brick_BC.tga", BaseColor),
("T_Brick_N.tga", Normal),
("T_Brick_ORM.tga", PackedOrm),
("brick_BaseMap.png", BaseColor),
("brick_MainTex.png", BaseColor),
("brick_BumpMap.png", Normal),
("brick_OcclusionMap.png", AmbientOcclusion),
("brick_EmissionMap.png", Emissive),
// Scan sites: ids, resolution and format tokens in the name
("Bricks059_4K-JPG_Color.jpg", BaseColor),
("Bricks059_4K-JPG_NormalGL.jpg", Normal),
("Bricks059_4K-JPG_Roughness.jpg", Roughness),
("Bricks059_1K_AmbientOcclusion.png", AmbientOcclusion),
("wall_1234_8k_Albedo.png", BaseColor),
("wood16bit_roughness.png", Roughness),
// Weak and inverted maps
("brick_bump.png", Height),
("WoodFloor_Gloss.png", Glossiness),
("wood_smoothness.png", Glossiness),
];
let wrong: Vec<String> =
table.iter().filter(|(name, want)| kind(name) != Some(*want)).map(|(name, want)| format!("{name}: got {:?}, want {want:?}", kind(name))).collect();
assert!(wrong.is_empty(), "{}", wrong.join("\n"));
}
#[test]
fn non_maps_are_ignored_with_a_reason() {
for (name, why) in [
("readme.txt", "not an image"),
("brick.mtlx", "not an image"),
("brick_preview.png", "preview image"),
("Brick_Thumbnail.jpg", "preview image"),
("sphere_render.png", "preview image"),
("._brick_albedo.png", "hidden or archive metadata file"),
("__MACOSX/brick_albedo.png", "hidden or archive metadata file"),
("brick.png", "unknown map name"),
("", "not an image"),
] {
assert_eq!(classify(name).unwrap_err(), why, "{name}");
}
// Recognised words with no channel here are reported as unused, not as maps
assert_eq!(kind("brick_cavity.png"), Some(Unused));
assert!(detect([("brick_cavity.png", 1)]).ignored.iter().any(|(_, w)| w == "unused map"));
}
#[test]
fn a_weak_word_loses_to_a_strong_one() {
// `bump` alone is a height map; next to a stronger word that word names the file
assert_eq!(kind("brick_bump.png"), Some(Height));
assert_eq!(kind("bump_brick_normal.png"), Some(Normal));
// A pair at the end beats an earlier single word
assert_eq!(kind("diffuse_wall_ambient_occlusion.png"), Some(AmbientOcclusion));
}
#[test]
fn normal_convention_comes_from_the_name() {
let n = |name: &str| classify(name).unwrap().normal;
assert_eq!(n("a_normal_gl.png"), Some(NormalFormat::OpenGl));
assert_eq!(n("a_normal_opengl.png"), Some(NormalFormat::OpenGl));
assert_eq!(n("a_normal_dx.png"), Some(NormalFormat::DirectX));
assert_eq!(n("a_NormalDX.png"), Some(NormalFormat::DirectX));
assert_eq!(n("a_nor_directx_2k.png"), Some(NormalFormat::DirectX));
assert_eq!(n("brick_normal_DirectX.png"), Some(NormalFormat::DirectX));
assert_eq!(n("brick_normal_d3d.png"), Some(NormalFormat::DirectX));
assert_eq!(n("a_normal.png"), None);
// `dx` on a map that is not a normal map says nothing
assert_eq!(n("a_roughness_dx.png"), None);
}
#[test]
fn packed_sequence_yields_to_a_later_map_word() {
assert_eq!(kind("brick_ao_rough_metal_basecolor.png"), Some(BaseColor));
assert_eq!(kind("brick_basecolor_ao_rough_metal.png"), Some(PackedOrm));
}
#[test]
fn several_candidates_pick_gl_then_resolution_then_size() {
let set = detect([
("m/n_dx.png", 10),
("m/n_gl.png", 5),
("m/albedo_1k.png", 900),
("m/albedo_4k.png", 100),
("m/albedo_2k.png", 500),
("m/rough.png", 7),
("m/rough.jpg", 9),
("m/notes.txt", 1),
("m/preview.png", 1),
("m/mystery.png", 1),
]);
let pick = |k| set.chosen.get(&k).map(|c| c.name.as_str());
// The convention that needs no flip wins even when the DirectX file is bigger
assert_eq!(pick(Normal), Some("m/n_gl.png"));
// The higher resolution token wins over file size
assert_eq!(pick(BaseColor), Some("m/albedo_4k.png"));
// No resolution token: the larger file
assert_eq!(pick(Roughness), Some("m/rough.jpg"));
assert_eq!(set.candidates[&BaseColor].len(), 3);
let why = |name: &str| set.ignored.iter().find(|(n, _)| n == name).map(|(_, w)| w.as_str());
assert_eq!(why("m/notes.txt"), Some("not an image"));
assert_eq!(why("m/preview.png"), Some("preview image"));
assert_eq!(why("m/mystery.png"), Some("unknown map name"));
assert_eq!(why("m/albedo_1k.png"), Some("another file is used for baseColor"));
}
#[test]
fn oversized_resolution_tokens_do_not_overflow() {
assert_eq!(classify("brick_4294967295k_albedo.png").unwrap().resolution, 0);
}
#[test]
fn empty_and_hostile_names_do_not_panic() {
assert!(detect([]).is_empty());
let long = "a".repeat(100_000);
let weird = [
"\u{0}.png",
"....png",
"ÄÖÜ_Ålbedo.png",
"🙂.png",
"_.png",
"-.exr",
long.as_str(),
"x/../../y_albedo.png",
"C:\\a\\b_albedo.png",
"99999999999999_albedo.png",
];
let set = detect(weird.iter().map(|n| (*n, 0)));
assert!(set.chosen.contains_key(&BaseColor));
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.