d84914ef1e5a
mod.rs
//! Texture export: render the maps of an [`ExportPreset`] from a texture set's composite, baked
//! mesh maps and UV coverage, entirely in memory (so the web build can export too).
//!
//! Each [`MapSpec`] packs sources into the R, G, B, A (or L) channels of one file. Sources are
//! composite channels, virtual maps (final normal in OpenGL or DirectX convention, glossiness,
//! mixed AO, F0), baked mesh maps and constants. The final normal is the baked normal, the
//! composited normal channel and the normal derived from height combined with Reoriented Normal
//! Mapping. Color maps are sRGB-encoded in 8/16-bit formats and linear in float formats; data
//! maps are always linear. Height is stored with 0.5 = zero (`h * 0.5 + 0.5`) in every format.
//!
//! A UV-tiled (UDIM) texture set writes one file per map per tile: `$udim` in the file name
//! becomes the tile number, and names without it get `.$udim` appended. Padding never crosses
//! tiles.
use std::collections::BTreeSet;
use std::io::Cursor;
use rayon::prelude::*;
use serde::{Deserialize, Serialize};
use texturecraft_compose::{BakedMaps, Composite};
use texturecraft_core::{AoMixing, BakedMap, BlockScales, Channel, ChannelKind, NormalFormat, NormalMixing, Project, TextureSet};
use texturecraft_geom::glam::Vec3;
use texturecraft_texel::{ColorSpace, DilationMap, linear_to_srgb};
use crate::{FormatError, MAX_IMAGE_SIZE, Result};
/// Height-to-normal slope: with strength 1, a height change of 1 across 1/16 of the texture
/// width tilts the normal 45ยฐ, at any resolution.
const HEIGHT_SPAN: f32 = 16.0;
const JPEG_QUALITY: u8 = 95;
/// Preset limits (user presets are untrusted JSON).
const MAX_MAPS: usize = 64;
const MAX_TEMPLATE: usize = 256;
const MAX_STEM: usize = 200;
/// Longest preset name.
pub const MAX_PRESET_NAME: usize = 64;
/// File name template variables with what they become (see [`list_outputs`]).
pub const FILE_TOKENS: [(&str, &str); 6] = [
("$mesh", "Mesh file name"),
("$textureSet", "Texture set name"),
("$project", "Project name"),
("$channel", "Channel or map id"),
("$colorSpace", "Colour maps: sRGB, linear, ACEScg or ACES2065-1; data maps: linear"),
("$udim", "UV tile number (1001 for sets without UV tiles)"),
];
/// Why `template` is not a valid file name template: path separators, `..`, control characters
/// and unknown `$` variables are refused.
pub fn template_error(template: &str) -> Option<String> {
if template.trim().is_empty() || template.len() > MAX_TEMPLATE {
return Some(format!("file name \"{template}\" is empty or longer than {MAX_TEMPLATE} bytes"));
}
if template.contains(['/', '\\']) || template.contains("..") || template.chars().any(char::is_control) {
return Some(format!("file name \"{template}\" contains a path separator, \"..\" or a control character"));
}
let mut rest = template;
while let Some(i) = rest.find('$') {
let tail = rest.get(i..).unwrap_or_default();
match FILE_TOKENS.iter().find(|(t, _)| tail.starts_with(t)) {
Some((t, _)) => rest = tail.get(t.len()..).unwrap_or_default(),
None => return Some(format!("file name \"{template}\" has an unknown variable (use {})", FILE_TOKENS.map(|(t, _)| t).join(", "))),
}
}
None
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum FileFormat {
Png,
Jpeg,
Tga,
Tiff,
Bmp,
Webp,
Exr,
Hdr,
}
impl FileFormat {
pub const ALL: [FileFormat; 8] =
[FileFormat::Png, FileFormat::Jpeg, FileFormat::Tga, FileFormat::Tiff, FileFormat::Bmp, FileFormat::Webp, FileFormat::Exr, FileFormat::Hdr];
pub fn extension(self) -> &'static str {
match self {
FileFormat::Png => "png",
FileFormat::Jpeg => "jpg",
FileFormat::Tga => "tga",
FileFormat::Tiff => "tif",
FileFormat::Bmp => "bmp",
FileFormat::Webp => "webp",
FileFormat::Exr => "exr",
FileFormat::Hdr => "hdr",
}
}
pub fn from_extension(ext: &str) -> Option<FileFormat> {
let ext = ext.trim_start_matches('.').to_ascii_lowercase();
match ext.as_str() {
"jpeg" => Some(FileFormat::Jpeg),
"tiff" => Some(FileFormat::Tiff),
_ => FileFormat::ALL.into_iter().find(|f| f.extension() == ext),
}
}
/// Bit depths this format is written with (16 and 32 are half and full float for EXR).
pub fn bit_depths(self) -> &'static [u8] {
match self {
FileFormat::Png | FileFormat::Tiff => &[8, 16],
FileFormat::Exr => &[16, 32],
FileFormat::Hdr => &[32],
_ => &[8],
}
}
/// Floating-point formats hold linear values.
pub fn is_float(self) -> bool {
matches!(self, FileFormat::Exr | FileFormat::Hdr)
}
/// The supported depth closest to `want` (ties go to the deeper one).
pub fn depth(self, want: u8) -> u8 {
self.bit_depths().iter().copied().min_by_key(|d| (d.abs_diff(want), std::cmp::Reverse(*d))).unwrap_or(8)
}
}
/// Destination channel of an output file. `L` alone writes grayscale; `L` + `A` gray + alpha.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub enum Dest {
R,
G,
B,
A,
L,
}
/// Maps computed at export time from several channels.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum VirtualMap {
/// Final tangent-space normal, +Y up the image.
NormalOpenGl,
/// Final tangent-space normal, green flipped.
NormalDirectX,
/// 1 โ roughness.
Glossiness,
/// Baked AO ร AO channel (per the texture set's AO mixing).
AoMixed,
/// Dielectric reflectance at normal incidence: 0.08 ร specular level.
F0,
/// 1 โ glossiness (specular/glossiness projects).
Roughness,
/// Tangent-space normal from the height channel alone (the export's normal convention).
HeightNormal,
/// Sheen color ร sheen weight (glTF's sheen color, a color map).
SheenTint,
}
impl VirtualMap {
pub const ALL: [VirtualMap; 8] = [
VirtualMap::NormalOpenGl,
VirtualMap::NormalDirectX,
VirtualMap::HeightNormal,
VirtualMap::Glossiness,
VirtualMap::Roughness,
VirtualMap::AoMixed,
VirtualMap::F0,
VirtualMap::SheenTint,
];
pub fn id(self) -> &'static str {
match self {
VirtualMap::NormalOpenGl | VirtualMap::NormalDirectX | VirtualMap::HeightNormal => "normal",
VirtualMap::Glossiness => "glossiness",
VirtualMap::Roughness => "roughness",
VirtualMap::AoMixed => "ambientOcclusion",
VirtualMap::F0 => "f0",
VirtualMap::SheenTint => "sheenTint",
}
}
pub fn label(self) -> &'static str {
match self {
VirtualMap::NormalOpenGl => "Normal OpenGL",
VirtualMap::NormalDirectX => "Normal DirectX",
VirtualMap::HeightNormal => "Normal from height",
VirtualMap::Glossiness => "Glossiness from roughness",
VirtualMap::Roughness => "Roughness from glossiness",
VirtualMap::AoMixed => "Mixed AO",
VirtualMap::F0 => "F0 from specular level",
VirtualMap::SheenTint => "Sheen color ร weight",
}
}
/// 3 for normals and colors, 1 otherwise.
pub fn components(self) -> usize {
match self {
VirtualMap::NormalOpenGl | VirtualMap::NormalDirectX | VirtualMap::HeightNormal | VirtualMap::SheenTint => 3,
_ => 1,
}
}
}
/// Where one output component comes from. `component` picks r/g/b of 3-component sources.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub enum SourceRef {
/// A composited channel. `Normal` means the final normal in the export normal format.
Channel {
channel: Channel,
#[serde(default)]
component: u8,
},
Virtual {
map: VirtualMap,
#[serde(default)]
component: u8,
},
Baked {
map: BakedMap,
#[serde(default)]
component: u8,
},
/// A constant (0 = black, 0.5 = gray, 1 = white).
Constant(f32),
}
impl SourceRef {
fn raw_component(&self) -> usize {
match self {
SourceRef::Channel { component, .. } | SourceRef::Virtual { component, .. } | SourceRef::Baked { component, .. } => *component as usize,
SourceRef::Constant(_) => 0,
}
}
fn component(&self) -> usize {
self.raw_component().min(2)
}
/// Components the source has (1 or 3; constants are 1).
pub fn components(&self) -> usize {
match self {
SourceRef::Channel { channel, .. } => channel.components(),
SourceRef::Virtual { map, .. } => map.components(),
SourceRef::Baked { map, .. } => map.components(),
SourceRef::Constant(_) => 1,
}
}
}
/// One exported file. `file` is a name template without extension (see [`list_outputs`]).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct MapSpec {
pub file: String,
pub format: FileFormat,
pub bit_depth: u8,
pub channels: Vec<(Dest, SourceRef)>,
/// Destination channels written as `1 - value` (absent in old files: none). The source value
/// is inverted before the colour-space encoding, so a colour map is inverted in linear light.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub inverted: Vec<Dest>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ExportPreset {
pub name: String,
pub maps: Vec<MapSpec>,
}
impl ExportPreset {
/// Structural checks for (untrusted) presets.
pub fn validate(&self) -> Result<()> {
let bad = |m: String| Err(FormatError::Invalid(format!("export preset \"{}\": {m}", self.name)));
if self.name.trim().is_empty() || self.name.chars().count() > MAX_PRESET_NAME || self.name.chars().any(char::is_control) {
return bad(format!("the name must be 1 to {MAX_PRESET_NAME} characters without control characters"));
}
if self.maps.len() > MAX_MAPS {
return bad(format!("more than {MAX_MAPS} maps"));
}
for m in &self.maps {
if let Some(e) = template_error(&m.file) {
return bad(e);
}
if !matches!(m.bit_depth, 8 | 16 | 32) {
return bad(format!("map \"{}\" has bit depth {} (8, 16 or 32)", m.file, m.bit_depth));
}
if m.channels.iter().any(|(_, s)| s.component() != s.raw_component()) {
return bad(format!("map \"{}\" picks a component other than 0, 1 or 2", m.file));
}
let dests: BTreeSet<Dest> = m.channels.iter().map(|(d, _)| *d).collect();
if dests.len() != m.channels.len() || m.channels.is_empty() {
return bad(format!("map \"{}\" needs distinct destination channels", m.file));
}
if dests.contains(&Dest::L) && dests.iter().any(|d| matches!(d, Dest::R | Dest::G | Dest::B)) {
return bad(format!("map \"{}\" mixes L with R/G/B", m.file));
}
let inv: BTreeSet<Dest> = m.inverted.iter().copied().collect();
if inv.len() != m.inverted.len() || !inv.is_subset(&dests) {
return bad(format!("map \"{}\" inverts a channel it does not write, or one twice", m.file));
}
if m.channels.iter().any(|(_, s)| matches!(s, SourceRef::Constant(v) if !v.is_finite())) {
return bad(format!("map \"{}\" has a non-finite constant", m.file));
}
}
Ok(())
}
}
/// UV padding of exported maps (texels outside the UV islands).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum Padding {
/// Uncovered texels are zero (transparent where there is alpha).
None,
/// Islands are dilated this many texels; beyond, texels are zero.
Dilation(u32),
/// Islands are dilated this many texels; beyond, texels hold the channel default.
DilationDefault(u32),
/// Every texel takes its nearest island's value.
Infinite,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ExportOptions {
pub preset: ExportPreset,
/// Write every map in this format instead of the preset's.
pub format_override: Option<FileFormat>,
pub bit_depth_override: Option<u8>,
pub padding: Padding,
/// Output size (power of two); None keeps the texture set resolution.
pub size: Option<u32>,
/// Normal convention for every normal output instead of the project's / preset's.
pub normal_format: Option<NormalFormat>,
/// UV-tiled sets: one image of the whole tile atlas per map instead of a file per tile
/// (for formats without UDIM support, with the mesh's UVs in atlas space).
pub atlas: bool,
/// The colour space of the colour maps (data maps are never converted); None writes sRGB
/// into 8/16-bit files and linear Rec.709 into float files (EXR, HDR).
#[serde(skip)]
pub color_space: Option<ColorSpace>,
}
impl ExportOptions {
/// The colour space colour maps are written in when `format` is used.
pub fn space_for(&self, format: FileFormat) -> ColorSpace {
self.color_space.unwrap_or(if format.is_float() { ColorSpace::LinearRec709 } else { ColorSpace::Srgb })
}
}
impl ExportOptions {
pub fn new(preset: ExportPreset) -> ExportOptions {
ExportOptions {
preset,
format_override: None,
bit_depth_override: None,
padding: Padding::Infinite,
size: None,
normal_format: None,
atlas: false,
color_space: None,
}
}
}
/// What is exported: one texture set's composite with its baked maps and UV coverage (one flag
/// per composite texel, row-major).
#[derive(Clone, Copy)]
pub struct ExportInput<'a> {
pub project: &'a Project,
pub ts: usize,
pub composite: &'a Composite,
pub baked: &'a BakedMaps,
pub coverage: &'a [bool],
pub mesh_name: &'a str,
}
#[derive(Clone, Debug, PartialEq)]
pub struct ExportedFile {
pub name: String,
pub bytes: Vec<u8>,
pub width: u32,
pub height: u32,
pub warnings: Vec<String>,
}
/// A file a preset produces for a texture set (see [`list_outputs`]).
#[derive(Clone, Debug, PartialEq)]
pub struct PlannedFile {
pub name: String,
/// Index into the preset's maps.
pub map: usize,
pub format: FileFormat,
pub bit_depth: u8,
/// UDIM number of the tile written (None: the whole set).
pub tile: Option<u32>,
/// For a tiled file, `name` with the tile number written as `<UDIM>` (what a material that
/// covers every tile refers to); None when the file isn't tiled.
pub udim_name: Option<String>,
pub warnings: Vec<String>,
}
// ---------------------------------------------------------------------------------------------
// Planning: which maps exist for a texture set and what their files are called
fn normal_present(set: &TextureSet) -> bool {
set.has_channel(Channel::Normal) || set.has_channel(Channel::Height) || set.baked.contains(&BakedMap::Normal)
}
/// A source with real data in this texture set (constants never count).
fn source_present(set: &TextureSet, s: &SourceRef) -> bool {
match s {
SourceRef::Channel { channel: Channel::Normal, .. } => normal_present(set),
SourceRef::Channel { channel, .. } => set.has_channel(*channel),
SourceRef::Virtual { map: VirtualMap::NormalOpenGl | VirtualMap::NormalDirectX, .. } => normal_present(set),
SourceRef::Virtual { map: VirtualMap::Glossiness, .. } => set.has_channel(Channel::Roughness),
SourceRef::Virtual { map: VirtualMap::AoMixed, .. } => set.has_channel(Channel::AmbientOcclusion) || set.baked.contains(&BakedMap::AmbientOcclusion),
SourceRef::Virtual { map: VirtualMap::F0, .. } => set.has_channel(Channel::SpecularLevel),
SourceRef::Virtual { map: VirtualMap::Roughness, .. } => set.has_channel(Channel::Glossiness),
SourceRef::Virtual { map: VirtualMap::HeightNormal, .. } => set.has_channel(Channel::Height),
SourceRef::Virtual { map: VirtualMap::SheenTint, .. } => set.has_channel(Channel::SheenWeight),
SourceRef::Baked { map, .. } => set.baked.contains(map),
SourceRef::Constant(_) => false,
}
}
/// The written components in order: L | L A | R G B | R G B A. Alpha from a channel the set
/// does not have is dropped.
fn layout<'m>(set: &TextureSet, map: &'m MapSpec) -> Vec<(Dest, &'m SourceRef)> {
let get = |d: Dest| map.channels.iter().find(|(x, _)| *x == d).map(|(_, s)| s);
let alpha = get(Dest::A).filter(|s| !matches!(s, SourceRef::Channel { channel, .. } if !set.has_channel(*channel)));
let black = &SourceRef::Constant(0.0);
let mut out = match get(Dest::L) {
Some(l) => vec![(Dest::L, l)],
None => [Dest::R, Dest::G, Dest::B].into_iter().map(|d| (d, get(d).unwrap_or(black))).collect(),
};
if let Some(a) = alpha {
out.push((Dest::A, a));
}
out
}
fn is_color(map: &MapSpec) -> bool {
map.channels.iter().any(|(d, s)| {
*d != Dest::A
&& match s {
SourceRef::Channel { channel, .. } => channel.kind() == ChannelKind::Color,
SourceRef::Virtual { map, .. } => *map == VirtualMap::SheenTint,
_ => false,
}
})
}
fn channel_label(map: &MapSpec) -> &'static str {
map.channels
.iter()
.find_map(|(_, s)| match s {
SourceRef::Channel { channel, .. } => Some(channel.id()),
SourceRef::Virtual { map, .. } => Some(map.id()),
SourceRef::Baked { map, .. } => Some(map.id()),
SourceRef::Constant(_) => None,
})
.unwrap_or("constant")
}
/// Keep `[A-Za-z0-9_.-]`, replace everything else with `_`; never empty or a reserved device name.
pub fn sanitize_file_stem(s: &str) -> String {
let mut out: String = s.chars().take(MAX_STEM).map(|c| if c.is_ascii_alphanumeric() || matches!(c, '_' | '.' | '-') { c } else { '_' }).collect();
if out.trim_matches('.').is_empty() {
out = "texture".into();
}
let device = out.split('.').next().unwrap_or_default().to_ascii_uppercase();
let reserved = matches!(device.as_str(), "CON" | "PRN" | "AUX" | "NUL")
|| (device.len() == 4 && (device.starts_with("COM") || device.starts_with("LPT")) && device.ends_with(|c: char| c.is_ascii_digit()));
if reserved {
out.insert(0, '_');
}
out
}
/// The files `opts` produces for texture set `ts`, without rendering (for the export dialog).
/// Template variables: [`FILE_TOKENS`].
pub fn list_outputs(project: &Project, ts: usize, mesh_name: &str, opts: &ExportOptions) -> Result<Vec<PlannedFile>> {
opts.preset.validate()?;
let set = project.texture_set(ts)?;
if let Some(s) = opts.size
&& (!s.is_power_of_two() || s > MAX_IMAGE_SIZE)
{
return Err(FormatError::Invalid(format!("export size {s} must be a power of two up to {MAX_IMAGE_SIZE}")));
}
let mut used = BTreeSet::new();
let mut out = Vec::new();
let tiles: Vec<Option<u32>> = if set.uv_tiles.is_empty() || opts.atlas { vec![None] } else { set.uv_tiles.iter().copied().map(Some).collect() };
for (i, map) in opts.preset.maps.iter().enumerate() {
if !map.channels.iter().any(|(_, s)| source_present(set, s)) {
continue;
}
let format = opts.format_override.unwrap_or(map.format);
let bit_depth = format.depth(opts.bit_depth_override.unwrap_or(map.bit_depth));
let space = opts.space_for(format);
let color_space = match (is_color(map), space) {
(false, _) | (true, ColorSpace::LinearRec709) => "linear",
(true, ColorSpace::Srgb) => "sRGB",
(true, other) => other.name(),
};
// Integer files clamp wide-gamut linear color to 0โ1
let clamps = is_color(map) && !format.is_float() && matches!(space, ColorSpace::AcesCg | ColorSpace::Aces2065);
// Append `$udim` to names for separate UV tiles
let template = if tiles.iter().any(Option::is_some) && !map.file.contains("$udim") { format!("{}.$udim", map.file) } else { map.file.clone() };
for &tile in &tiles {
let stem = template
.replace("$udim", &tile.unwrap_or(1001).to_string())
.replace("$project", &project.name)
.replace("$mesh", mesh_name)
.replace("$textureSet", &set.name)
.replace("$channel", channel_label(map))
.replace("$colorSpace", color_space);
// Replace the tile number with `<UDIM>` in the shared name
let token_stem = tile.map(|_| {
let t = template
.replace("$udim", "UDIMTOKEN")
.replace("$project", &project.name)
.replace("$mesh", mesh_name)
.replace("$textureSet", &set.name)
.replace("$channel", channel_label(map))
.replace("$colorSpace", color_space);
sanitize_file_stem(&t)
});
let stem = sanitize_file_stem(&stem);
let ext = format.extension();
let mut name = format!("{stem}.{ext}");
let mut warnings = Vec::new();
if clamps {
warnings.push(format!(
"{} colours outside 0-1 are clamped in {} files; use EXR or HDR to keep them",
space.name(),
format.extension().to_uppercase()
));
}
// Compare names case-insensitively for Windows and macOS
let mut k = 2;
while used.contains(&name.to_ascii_lowercase()) {
name = format!("{stem}_{k}.{ext}");
k += 1;
}
if k > 2 {
warnings.push(format!("\"{stem}.{ext}\" is produced by more than one map; this one was renamed to \"{name}\""));
}
used.insert(name.to_ascii_lowercase());
// Use a UDIM name only when substituting its tile recovers the output name
// Truncation or literal placeholder text can make that substitution ambiguous
let udim_name = token_stem.filter(|t| tile.is_some_and(|n| t.contains("UDIMTOKEN") && t.replace("UDIMTOKEN", &n.to_string()) == stem)).map(|t| {
let renamed = if k > 2 { format!("_{}", k - 1) } else { String::new() };
format!("{t}{renamed}.{ext}").replace("UDIMTOKEN", "<UDIM>")
});
out.push(PlannedFile { name, map: i, format, bit_depth, tile, udim_name, warnings });
}
}
Ok(out)
}
// ---------------------------------------------------------------------------------------------
// Sampling
/// Which texel a value is taken from.
#[derive(Clone, Copy, PartialEq)]
enum At {
Texel(u32, u32),
/// The channel default (padding beyond the dilation distance).
Default,
}
struct Sampler<'a> {
set: &'a TextureSet,
comp: &'a Composite,
baked: &'a BakedMaps,
coverage: &'a [bool],
/// Composite width.
res: u32,
/// Texels per atlas block (`res` for a classic set): the height slope and the Sobel window
/// follow the block.
tile_res: u32,
/// The share of its block each tile fills: a smaller tile's height slope shrinks with it.
scales: BlockScales,
/// Normal convention overriding every normal output.
normal_override: Option<NormalFormat>,
project_normal: NormalFormat,
}
fn unpack(v: [f32; 3]) -> Vec3 {
(Vec3::from(v) * 2.0 - Vec3::ONE).try_normalize().unwrap_or(Vec3::Z)
}
/// Reoriented Normal Mapping: `detail` re-expressed around `base` (unit tangent-space vectors).
pub fn rnm(base: Vec3, detail: Vec3) -> Vec3 {
let t = base + Vec3::Z;
let u = detail * Vec3::new(-1.0, -1.0, 1.0);
(t * t.dot(u) / t.z.max(1e-4) - u).try_normalize().unwrap_or(base)
}
impl Sampler<'_> {
fn channel(&self, c: Channel, at: At) -> [f32; 3] {
match at {
At::Texel(x, y) if self.set.has_channel(c) => self.comp.value(c, x, y),
_ => c.default_value(),
}
}
fn baked(&self, m: BakedMap, at: At) -> [f32; 3] {
match at {
At::Texel(x, y) if self.set.baked.contains(&m) => {
self.baked.sample_working(m, x, y, (self.res, self.comp.height), &self.scales).unwrap_or(m.neutral())
}
_ => m.neutral(),
}
}
fn covered(&self, x: u32, y: u32) -> bool {
self.coverage.get((y as usize) * self.res as usize + x as usize).copied().unwrap_or(false)
}
/// Normal from the height channel (3ร3 Sobel; uncovered neighbours repeat the centre).
fn height_normal(&self, x: u32, y: u32) -> Vec3 {
let center = self.channel(Channel::Height, At::Texel(x, y))[0];
// Clamped to the texel's UV tile.
let t = self.tile_res.max(1);
let (x0, y0, last) = ((x / t * t) as i64, (y / t * t) as i64, t as i64 - 1);
let h = |dx: i64, dy: i64| {
let (sx, sy) = ((x as i64 + dx).clamp(x0, x0 + last) as u32, (y as i64 + dy).clamp(y0, y0 + last) as u32);
if self.covered(sx, sy) { self.channel(Channel::Height, At::Texel(sx, sy))[0] } else { center }
};
let gx = (h(1, -1) + 2.0 * h(1, 0) + h(1, 1) - h(-1, -1) - 2.0 * h(-1, 0) - h(-1, 1)) / 8.0;
let gy = (h(-1, 1) + 2.0 * h(0, 1) + h(1, 1) - h(-1, -1) - 2.0 * h(0, -1) - h(1, -1)) / 8.0;
let s = self.set.height_strength * self.tile_res as f32 * self.scales.at(x, y) / HEIGHT_SPAN;
// Image y points down; OpenGL normals have +Y up the image.
Vec3::new(-gx * s, gy * s, 1.0).try_normalize().unwrap_or(Vec3::Z)
}
/// The final tangent-space normal (OpenGL): baked normal โ (height โ normal channel).
fn final_normal(&self, at: At) -> Vec3 {
let At::Texel(x, y) = at else { return Vec3::Z };
let base = if self.set.baked.contains(&BakedMap::Normal) { unpack(self.baked(BakedMap::Normal, at)) } else { Vec3::Z };
let mut detail = if self.set.has_channel(Channel::Normal) { unpack(self.channel(Channel::Normal, at)) } else { Vec3::Z };
if self.set.normal_mixing == NormalMixing::Combine && self.set.has_channel(Channel::Height) && self.set.height_strength != 0.0 {
detail = rnm(self.height_normal(x, y), detail);
}
rnm(base, detail)
}
fn normal(&self, at: At, format: NormalFormat, cache: &mut Option<Vec3>) -> [f32; 3] {
let n = *cache.get_or_insert_with(|| self.final_normal(at));
self.pack_normal(n, format)
}
/// A unit OpenGL normal packed into 0..1 in `format` (or the override).
fn pack_normal(&self, n: Vec3, format: NormalFormat) -> [f32; 3] {
let y = if self.normal_override.unwrap_or(format) == NormalFormat::DirectX { -n.y } else { n.y };
[n.x * 0.5 + 0.5, y * 0.5 + 0.5, n.z * 0.5 + 0.5]
}
fn sample(&self, src: &SourceRef, at: At, cache: &mut Option<Vec3>) -> f32 {
let k = src.component();
let v = match src {
SourceRef::Constant(v) => return *v,
SourceRef::Channel { channel: Channel::Normal, .. } => self.normal(at, self.project_normal, cache),
SourceRef::Channel { channel, .. } => {
let v = self.channel(*channel, at);
if channel.kind() == ChannelKind::Signed { v.map(|h| h * 0.5 + 0.5) } else { v }
}
SourceRef::Virtual { map, .. } => match map {
VirtualMap::NormalOpenGl => self.normal(at, NormalFormat::OpenGl, cache),
VirtualMap::NormalDirectX => self.normal(at, NormalFormat::DirectX, cache),
VirtualMap::Glossiness => [1.0 - self.channel(Channel::Roughness, at)[0]; 3],
VirtualMap::F0 => [0.08 * self.channel(Channel::SpecularLevel, at)[0]; 3],
VirtualMap::Roughness => [1.0 - self.channel(Channel::Glossiness, at)[0]; 3],
VirtualMap::SheenTint => self.channel(Channel::SheenColor, at).map(|c| c * self.channel(Channel::SheenWeight, at)[0]),
VirtualMap::HeightNormal => {
let n = match at {
At::Texel(x, y) => self.height_normal(x, y),
At::Default => Vec3::Z,
};
self.pack_normal(n, self.project_normal)
}
VirtualMap::AoMixed => {
let ch = self.channel(Channel::AmbientOcclusion, at)[0];
let baked = self.baked(BakedMap::AmbientOcclusion, at)[0];
[if self.set.ao_mixing == AoMixing::Multiply { ch * baked } else { ch }; 3]
}
},
SourceRef::Baked { map, .. } => {
let v = self.baked(*map, at);
// Tangent-space maps are stored with OpenGL green, like the normal map: write the format of the export
if matches!(map, BakedMap::Normal | BakedMap::BentNormal) && self.normal_override.unwrap_or(self.project_normal) == NormalFormat::DirectX {
[v[0], 1.0 - v[1], v[2]]
} else {
v
}
}
};
v.get(k).copied().unwrap_or(0.0)
}
}
// ---------------------------------------------------------------------------------------------
// Rendering.
/// Render every file of `opts` for `input`'s texture set.
pub fn render_maps(input: &ExportInput, opts: &ExportOptions) -> Result<Vec<ExportedFile>> {
let planned = list_outputs(input.project, input.ts, input.mesh_name, opts)?;
let set = input.project.texture_set(input.ts)?;
let (res, height) = (input.composite.resolution, input.composite.height);
let grid = set.tile_grid();
let tile_res = res / grid.map_or(1, |g| g.cols.max(1));
if tile_res == 0 || tile_res > MAX_IMAGE_SIZE || height != tile_res * grid.map_or(1, |g| g.rows) {
return Err(FormatError::Invalid(format!("composite size {res}ร{height} does not fit texture set \"{}\"", set.name)));
}
if input.coverage.len() != res as usize * height as usize {
return Err(FormatError::Invalid(format!("coverage has {} texels, expected {res}ร{height}", input.coverage.len())));
}
// Padding stays inside each UV tile
let dmap = match opts.padding {
Padding::None => None,
Padding::Dilation(d) | Padding::DilationDefault(d) => Some(DilationMap::in_blocks(input.coverage, res, height, Some(d), tile_res)),
Padding::Infinite => Some(DilationMap::in_blocks(input.coverage, res, height, None, tile_res)),
};
let beyond_default = matches!(opts.padding, Padding::DilationDefault(_) | Padding::Infinite);
let sampler = Sampler {
set,
comp: input.composite,
baked: input.baked,
coverage: input.coverage,
res,
tile_res,
scales: set.block_scales(),
normal_override: opts.normal_format,
project_normal: input.project.normal_format,
};
planned
.into_iter()
.map(|p| {
let map = opts.preset.maps.get(p.map).ok_or_else(|| FormatError::Invalid("planned map out of range".into()))?;
let lay = layout(set, map);
let n = lay.len();
let inverted: Vec<bool> = lay.iter().map(|(d, _)| map.inverted.contains(d)).collect();
// The texels written: one tile, or the whole set
let (x0, y0, w, h) = match (p.tile, grid) {
(Some(t), Some(g)) => {
let (bx, by) = g.block(t).ok_or_else(|| FormatError::Invalid(format!("UV tile {t} is not in the set's grid")))?;
// A tile smaller than its block fills the block's top-left corner
let side = ((tile_res as f32 * set.tile_scale(t)).round() as u32).clamp(1, tile_res);
(bx * tile_res, by * tile_res, side, side)
}
_ => (0, 0, res, height),
};
let mut data = vec![0.0f32; w as usize * h as usize * n];
data.par_chunks_mut(w as usize * n).enumerate().for_each(|(row_y, row)| {
let y = y0 + row_y as u32;
for (col, x) in (x0..x0 + w).enumerate() {
let at = if sampler.covered(x, y) {
Some(At::Texel(x, y))
} else {
match dmap.as_ref().and_then(|d| d.source(x, y)) {
Some((sx, sy)) => Some(At::Texel(sx, sy)),
None => beyond_default.then_some(At::Default),
}
};
let Some(at) = at else { continue };
let mut cache = None;
for (k, (_, src)) in lay.iter().enumerate() {
if let Some(v) = row.get_mut(col * n + k) {
let s = sampler.sample(src, at, &mut cache);
*v = if inverted.get(k).copied().unwrap_or(false) { 1.0 - s } else { s };
}
}
}
});
// `size` is per tile: an atlas scales with it
let scale = |v: u32| (u64::from(v) * u64::from(opts.size.unwrap_or(tile_res)) / u64::from(tile_res)) as u32;
let size = (scale(w), scale(h));
let data = resize(data, (w, h), n, size);
// Integer sRGB converts in `encode`; other color spaces convert here
let space = opts.space_for(p.format);
let rgb = lay.len() >= 3 && lay.iter().take(3).map(|(d, _)| *d).eq([Dest::R, Dest::G, Dest::B]);
let mut data = data;
let mut warnings = p.warnings;
let convert = is_color(map) && (space != ColorSpace::Srgb || p.format.is_float()) && space != ColorSpace::LinearRec709;
if convert && rgb {
data.par_chunks_mut(n).for_each(|px| {
if let [r, g, b, ..] = px {
[*r, *g, *b] = space.from_linear_rec709([*r, *g, *b]);
}
});
} else if convert {
warnings.push(format!("\"{}\" packs colour into one channel (L), so it is written in linear Rec.709, not {}", p.name, space.name()));
}
let srgb: Vec<bool> = lay.iter().map(|(d, _)| *d != Dest::A && is_color(map) && !p.format.is_float() && space == ColorSpace::Srgb).collect();
// A colour space the user chose is written into the colour maps (data maps have none)
let embed = (opts.color_space.is_some() && is_color(map) && rgb).then_some(space);
let bytes = encode(p.format, p.bit_depth, size, n, &data, &srgb, embed, &mut warnings)?;
Ok(ExportedFile { name: p.name, bytes, width: size.0, height: size.1, warnings })
})
.collect()
}
/// Resample a `from` (width, height) image of `n` components to `to` (same aspect): box filter
/// when shrinking by an integer factor, bilinear otherwise.
fn resize(data: Vec<f32>, from: (u32, u32), n: usize, to: (u32, u32)) -> Vec<f32> {
if to == from || from.0 == 0 || from.1 == 0 || to.0 == 0 || to.1 == 0 {
return data;
}
let ((r, rh), (t, th)) = ((from.0 as usize, from.1 as usize), (to.0 as usize, to.1 as usize));
let mut out = vec![0.0f32; t * th * n];
let px = |x: usize, y: usize, k: usize| data.get((y * r + x) * n + k).copied().unwrap_or(0.0);
let boxed = r > t && r % t == 0 && rh % th == 0 && r / t == rh / th;
out.par_chunks_mut(t * n).enumerate().for_each(|(y, row)| {
for x in 0..t {
for k in 0..n {
let v = if boxed {
let f = r / t;
let sum: f32 = (0..f).flat_map(|dy| (0..f).map(move |dx| (dx, dy))).map(|(dx, dy)| px(x * f + dx, y * f + dy, k)).sum();
sum / (f * f) as f32
} else {
let (sx, sy) = (r as f32 / t as f32, rh as f32 / th as f32);
let (fx, fy) = (((x as f32 + 0.5) * sx - 0.5).max(0.0), ((y as f32 + 0.5) * sy - 0.5).max(0.0));
let (x0, y0) = ((fx as usize).min(r - 1), (fy as usize).min(rh - 1));
let (x1, y1) = ((x0 + 1).min(r - 1), (y0 + 1).min(rh - 1));
let (ax, ay) = (fx - x0 as f32, fy - y0 as f32);
let top = px(x0, y0, k) * (1.0 - ax) + px(x1, y0, k) * ax;
let bottom = px(x0, y1, k) * (1.0 - ax) + px(x1, y1, k) * ax;
top * (1.0 - ay) + bottom * ay
};
if let Some(o) = row.get_mut(x * n + k) {
*o = v;
}
}
}
});
out
}
/// Encode a `size` (width, height) image of `n` components (1 L, 2 LA, 3 RGB, 4 RGBA; linear
/// values).
#[allow(clippy::too_many_arguments)]
fn encode(
format: FileFormat,
depth: u8,
size: (u32, u32),
n: usize,
data: &[f32],
srgb: &[bool],
embed: Option<ColorSpace>,
warnings: &mut Vec<String>,
) -> Result<Vec<u8>> {
let failed = |e: &dyn std::fmt::Display| FormatError::Invalid(format!("{} encoding failed: {e}", format.extension()));
// Embed ICC or EXR chromaticities only where the format supports them
if let Some(space) = embed
&& matches!(format, FileFormat::Tga | FileFormat::Bmp | FileFormat::Hdr)
{
warnings.push(format!("{} files can't record a colour space; the colours are in {}", format.extension().to_ascii_uppercase(), space.name()));
}
match format {
FileFormat::Exr => return write_exr(size, n, data, depth == 16, embed).map_err(|e| failed(&e)),
FileFormat::Hdr => {
if n == 2 || n == 4 {
warnings.push("HDR has no alpha channel; alpha was dropped".into());
}
let rgb = remap(data, n, if n <= 2 { &[0, 0, 0] } else { &[0, 1, 2] });
let bytes: Vec<u8> = rgb.iter().flat_map(|v| v.to_ne_bytes()).collect();
return write_image(format, &bytes, size, image::ExtendedColorType::Rgb32F, None).map_err(|e| failed(&e));
}
_ => {}
}
// Integer formats: transfer function and quantization first, then fit the channel layout
let encoded: Vec<f32> =
data.iter().enumerate().map(|(i, v)| if srgb.get(i % n).copied().unwrap_or(false) { linear_to_srgb(*v) } else { v.clamp(0.0, 1.0) }).collect();
let (encoded, n) = match (format, n) {
(FileFormat::Jpeg, 2 | 4) => {
warnings.push("JPEG has no alpha channel; alpha was dropped".into());
(remap(&encoded, n, if n == 2 { &[0] } else { &[0, 1, 2] }), n - 1)
}
(FileFormat::Tiff, 2) => (remap(&encoded, 2, &[0, 0, 0, 1]), 4),
_ => (encoded, n),
};
use image::ExtendedColorType as C;
let (bytes, color) = if depth == 16 {
let b: Vec<u8> = encoded.iter().flat_map(|v| ((v * 65535.0 + 0.5) as u16).to_ne_bytes()).collect();
(b, [C::L16, C::La16, C::Rgb16, C::Rgba16].get(n.wrapping_sub(1)).copied().unwrap_or(C::Rgba16))
} else {
let b: Vec<u8> = encoded.iter().map(|v| (v * 255.0 + 0.5) as u8).collect();
(b, [C::L8, C::La8, C::Rgb8, C::Rgba8].get(n.wrapping_sub(1)).copied().unwrap_or(C::Rgba8))
};
let icc = embed.and_then(crate::icc::profile);
write_image(format, &bytes, size, color, icc).map_err(|e| failed(&e))
}
/// Pick components `pick` from every texel of an `n`-component image.
fn remap(data: &[f32], n: usize, pick: &[usize]) -> Vec<f32> {
data.chunks_exact(n.max(1)).flat_map(|px| pick.iter().map(|k| px.get(*k).copied().unwrap_or(0.0))).collect()
}
/// Encode `bytes` as `format`, with `icc` (an ICC profile) embedded where the format has a place for one.
fn write_image(format: FileFormat, bytes: &[u8], (w, h): (u32, u32), color: image::ExtendedColorType, icc: Option<Vec<u8>>) -> image::ImageResult<Vec<u8>> {
use image::ImageEncoder;
let mut out = Cursor::new(Vec::new());
// `set_icc_profile` says no (an error to ignore) for an encoder without a place for it
let fmt = match format {
FileFormat::Jpeg => {
let mut enc = image::codecs::jpeg::JpegEncoder::new_with_quality(&mut out, JPEG_QUALITY);
if let Some(p) = icc {
let _ = enc.set_icc_profile(p);
}
enc.write_image(bytes, w, h, color)?;
return Ok(out.into_inner());
}
FileFormat::Png if icc.is_some() => {
let mut enc = image::codecs::png::PngEncoder::new(&mut out);
if let Some(p) = icc {
let _ = enc.set_icc_profile(p);
}
enc.write_image(bytes, w, h, color)?;
return Ok(out.into_inner());
}
FileFormat::Tiff if icc.is_some() => {
let mut enc = image::codecs::tiff::TiffEncoder::new(&mut out);
if let Some(p) = icc {
let _ = enc.set_icc_profile(p);
}
enc.write_image(bytes, w, h, color)?;
return Ok(out.into_inner());
}
FileFormat::Webp if icc.is_some() => {
let mut enc = image::codecs::webp::WebPEncoder::new_lossless(&mut out);
if let Some(p) = icc {
let _ = enc.set_icc_profile(p);
}
enc.write_image(bytes, w, h, color)?;
return Ok(out.into_inner());
}
FileFormat::Png => image::ImageFormat::Png,
FileFormat::Tga => image::ImageFormat::Tga,
FileFormat::Tiff => image::ImageFormat::Tiff,
FileFormat::Bmp => image::ImageFormat::Bmp,
FileFormat::Webp => image::ImageFormat::WebP,
FileFormat::Hdr => image::ImageFormat::Hdr,
FileFormat::Exr => image::ImageFormat::OpenExr,
};
image::write_buffer_with_format(&mut out, bytes, w, h, color, fmt)?;
Ok(out.into_inner())
}
/// OpenEXR with Y / YA / RGB / RGBA channels, half or full float, ZIP compression.
fn write_exr((w, h): (u32, u32), n: usize, data: &[f32], half: bool, space: Option<ColorSpace>) -> exr::error::Result<Vec<u8>> {
use exr::prelude::*;
let names: &[&str] = match n {
1 => &["Y"],
2 => &["Y", "A"],
3 => &["R", "G", "B"],
_ => &["R", "G", "B", "A"],
};
let channels: SmallVec<[AnyChannel<FlatSamples>; 4]> = names
.iter()
.enumerate()
.map(|(k, name)| {
let plane = data.iter().skip(k).step_by(n.max(1));
let samples = if half { FlatSamples::F16(plane.map(|v| f16::from_f32(*v)).collect()) } else { FlatSamples::F32(plane.copied().collect()) };
AnyChannel::new(*name, samples)
})
.collect();
let layer = Layer::new((w as usize, h as usize), LayerAttributes::default(), Encoding::SMALL_LOSSLESS, AnyChannels::sort(channels));
let mut out = Cursor::new(Vec::new());
let mut image = Image::from_layer(layer);
// Store primaries and white point in the OpenEXR attribute
if let Some(space) = space {
let [r, g, b, white] = space.chromaticities().map(|xy| Vec2(xy[0] as f32, xy[1] as f32));
image.attributes.chromaticities = Some(exr::meta::attribute::Chromaticities { red: r, green: g, blue: b, white });
}
let writer = image.write();
// The web build has no worker threads
#[cfg(target_arch = "wasm32")]
let writer = writer.non_parallel();
writer.to_buffered(&mut out)?;
Ok(out.into_inner())
}
/// Write exported files into `dir` (created if missing), each atomically (`name.tmp`, then
/// rename). Names must be plain file names.
#[cfg(not(target_arch = "wasm32"))]
pub fn write_files(files: &[ExportedFile], dir: &std::path::Path) -> Result<Vec<std::path::PathBuf>> {
std::fs::create_dir_all(dir)?;
files
.iter()
.map(|f| {
// Cap the sanitized stem before adding the extension
let (stem, ext) = f.name.rsplit_once('.').unwrap_or((&f.name, ""));
if f.name.is_empty() || stem != sanitize_file_stem(stem) || !ext.chars().all(|c| c.is_ascii_alphanumeric()) || f.name.trim_matches('.').is_empty() {
return Err(FormatError::Invalid(format!("\"{}\" is not a plain file name", f.name)));
}
let path = dir.join(&f.name);
crate::write_atomic(&path, &f.bytes)?;
Ok(path)
})
.collect()
}
#[cfg(test)]
mod tests;
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.