d84914ef1e5a
orb_preview.rs
//! Smart mask and smart material previews share one baked [`primitives::preview_orb`]
//! Presets use `mask.smart.apply`, materials use [`materials::apply`], both read back from the compositor
use std::collections::{BTreeMap, BTreeSet};
use serde_json::json;
use texturecraft_core::{BakeResolution, BakedMap, Channel, CurvatureMethod, LayerId};
use texturecraft_geom::glam::Vec3;
use texturecraft_geom::primitives;
use texturecraft_texel::TILE;
pub use crate::mask_preview_pixel::MaskPreviewPixel;
pub use crate::material_preview_pixel::MaterialPreviewPixel;
use crate::orb_camera::OrbCamera;
use crate::preview::Sample;
use crate::session::Document;
use crate::{EngineError, Result, Session, materials};
/// Bake resolution in texels; 256 loses the thin edge lines
const TEXTURE_PX: u32 = 512;
/// Camera rays per preview pixel along each axis (anti-aliased outline)
const SUPERSAMPLE: usize = 2;
/// Bound camera samples and output allocations for shelf previews
pub const MAX_PREVIEW_SIZE_PX: usize = 512;
/// AO and thickness rays per texel; thumbnail detail needs fewer than the default
const OCCLUSION_RAYS: u32 = 12;
/// Curvature rays per texel; thumbnail detail needs fewer than the default
const CURVATURE_RAYS: u32 = 12;
/// Radius relative to the bounding box; isolates panel edges from the round body
const CURVATURE_RADIUS: f32 = 0.005;
/// The mesh maps the smart mask generators read; smart materials build on the same presets
const MAPS: [BakedMap; 3] = [BakedMap::Curvature, BakedMap::AmbientOcclusion, BakedMap::Thickness];
/// Keep camera views for the thumbnail and hover preview sizes
const CAMERAS_KEPT: usize = 2;
/// The channels a material preview shows, in [`Sample`] order
const MATERIAL_CHANNELS: [Channel; 4] = [Channel::BaseColor, Channel::Metallic, Channel::Roughness, Channel::Height];
/// The orb's only texture set
const SET: usize = 0;
/// The baked orb and, per preview size, what its camera sees
pub struct OrbPreview {
session: Session,
/// The layer smart masks are applied to
layer: LayerId,
/// The baked document and selection, restored before each material
bare: (Document, BTreeMap<usize, LayerId>),
/// Cached camera views, least recently used first
cameras: Vec<OrbCamera>,
}
impl OrbPreview {
/// Bake the orb once (previews of any size reuse it)
pub fn new() -> Result<OrbPreview> {
let mut session = Session::new_project("Orb preview", primitives::preview_orb(), "builtin:preview_orb", None, TEXTURE_PX)?;
let set = session.doc.project.texture_set_mut(SET)?;
set.bake.common.resolution = BakeResolution::from_pixels(TEXTURE_PX).ok_or_else(|| EngineError::Other("invalid bake resolution".into()))?;
set.bake.high_poly.use_low_as_high = true;
set.bake.maps.curvature.parameters.method = CurvatureMethod::Mesh;
set.bake.maps.curvature.parameters.mesh.sampling_radius = CURVATURE_RADIUS;
set.bake.maps.curvature.parameters.mesh.rays = CURVATURE_RAYS;
set.bake.maps.ao.parameters.rays.rays = OCCLUSION_RAYS;
set.bake.maps.thickness.parameters.rays.rays = OCCLUSION_RAYS;
for map in BakedMap::ALL {
set.bake.maps.set_enabled(map, MAPS.contains(&map));
}
let layer = *set.stack.first().ok_or_else(|| EngineError::Other("the preview has no layer".into()))?;
session.bake_now(SET, false)?;
let bare = (session.doc.clone(), session.selected.clone());
Ok(OrbPreview { session, layer, bare, cameras: Vec::new() })
}
/// Row-major `size²` pixels of smart mask `id`, with None outside the shape
/// Returns None for unknown masks or sizes outside 1..=[`MAX_PREVIEW_SIZE_PX`]
pub fn mask(&mut self, id: &str, size: usize) -> Option<Vec<Option<MaskPreviewPixel>>> {
if !valid_size(size) {
return None;
}
crate::execute(&mut self.session, "mask.smart.apply", &json!({ "name": id, "layer": self.layer.0 })).ok()?;
// Previews need no undo history; retaining snapshots grows memory across presets
self.session.undo.clear();
let camera = camera_for(&mut self.cameras, &self.session, size)?;
let values = self.session.mask_at(self.layer, &camera.texels)?;
let sub_pixels = (SUPERSAMPLE * SUPERSAMPLE) as f32;
let pixels = (0..size * size)
.map(|pixel| {
let (mut mask_sum, mut normal_sum, mut hits) = (0.0, Vec3::ZERO, 0.0);
for (texel, normal) in pixel_hits(camera, size, pixel) {
mask_sum += values.get(texel).copied().unwrap_or(0.0);
normal_sum += normal;
hits += 1.0;
}
(hits > 0.0).then(|| MaskPreviewPixel { mask: mask_sum / hits, normal: normal_sum.normalize_or_zero(), coverage: hits / sub_pixels })
})
.collect();
Some(pixels)
}
/// Row-major `size²` pixels of built-in material `id`, with None outside the shape
/// Returns None for unknown materials or sizes outside 1..=[`MAX_PREVIEW_SIZE_PX`]
pub fn material(&mut self, id: &str, size: usize) -> Option<Vec<Option<MaterialPreviewPixel>>> {
if !valid_size(size) {
return None;
}
// Each material goes on the bare shape, not over the previous one
(self.session.doc, self.session.selected) = self.bare.clone();
let applied = materials::apply(&mut self.session, id);
// Previews need no undo history; retaining snapshots grows memory across materials
self.session.undo.clear();
applied.ok()?;
let camera = camera_for(&mut self.cameras, &self.session, size)?;
let values = material_at(&self.session, &camera.texels)?;
let sub_pixels = (SUPERSAMPLE * SUPERSAMPLE) as f32;
let pixels = (0..size * size)
.map(|pixel| {
let mut sum = Sample { base: [0.0; 3], metallic: 0.0, roughness: 0.0, height: 0.0 };
let (mut normal_sum, mut hits) = (Vec3::ZERO, 0.0);
for (texel, normal) in pixel_hits(camera, size, pixel) {
let Some(value) = values.get(texel) else { continue };
sum.base = [0, 1, 2].map(|component| sum.base[component] + value.base[component]);
sum.metallic += value.metallic;
sum.roughness += value.roughness;
sum.height += value.height;
normal_sum += normal;
hits += 1.0;
}
(hits > 0.0).then(|| {
let mean = Sample {
base: sum.base.map(|component| component / hits),
metallic: sum.metallic / hits,
roughness: sum.roughness / hits,
height: sum.height / hits,
};
MaterialPreviewPixel { sample: mean, normal: normal_sum.normalize_or_zero(), coverage: hits / sub_pixels }
})
})
.collect();
Some(pixels)
}
}
/// Preview sizes the camera may allocate
fn valid_size(size: usize) -> bool {
(1..=MAX_PREVIEW_SIZE_PX).contains(&size)
}
/// The rays through `pixel` of a `size²` preview that hit the shape, as (texel index, view-space normal)
fn pixel_hits(camera: &OrbCamera, size: usize, pixel: usize) -> impl Iterator<Item = (usize, Vec3)> + '_ {
let (x, y) = (pixel % size, pixel / size);
(0..SUPERSAMPLE * SUPERSAMPLE).filter_map(move |sub_pixel| {
let (sub_x, sub_y) = (sub_pixel % SUPERSAMPLE, sub_pixel / SUPERSAMPLE);
let ray = (y * SUPERSAMPLE + sub_y) * camera.rays_per_side + x * SUPERSAMPLE + sub_x;
camera.samples.get(ray).copied().flatten()
})
}
/// The material values at `texels`, compositing only the tiles that hold them
fn material_at(session: &Session, texels: &[(u32, u32)]) -> Option<Vec<Sample>> {
let tiles: BTreeSet<(u32, u32)> = texels.iter().map(|(x, y)| (x / TILE, y / TILE)).collect();
let tiles: Vec<(u32, u32)> = tiles.into_iter().collect();
session.with_inputs(SET, |inputs| {
let mut composite = texturecraft_compose::Composite::new(&MATERIAL_CHANNELS, TEXTURE_PX);
texturecraft_compose::composite_tiles(inputs, &mut composite, &tiles);
let samples = texels
.iter()
.map(|&(x, y)| {
let [base, metallic, roughness, height] = MATERIAL_CHANNELS.map(|channel| composite.value(channel, x, y));
Sample { base, metallic: metallic[0], roughness: roughness[0], height: height[0] }
})
.collect();
Some(samples)
})
}
/// Cache one camera per preview size, evicting the least recently used view
fn camera_for<'a>(cameras: &'a mut Vec<OrbCamera>, session: &Session, size: usize) -> Option<&'a OrbCamera> {
let rays_per_side = size * SUPERSAMPLE;
let camera = match cameras.iter().position(|camera| camera.rays_per_side == rays_per_side) {
Some(index) => cameras.remove(index),
None => OrbCamera::new(session, TEXTURE_PX, rays_per_side),
};
if cameras.len() >= CAMERAS_KEPT {
cameras.remove(0);
}
cameras.push(camera);
cameras.last()
}
#[cfg(test)]
mod tests {
use super::*;
/// Mean absolute difference of the masks of two previews over the pixels both see
fn difference(a: &[Option<MaskPreviewPixel>], b: &[Option<MaskPreviewPixel>]) -> f32 {
let pairs: Vec<(f32, f32)> = a.iter().zip(b).filter_map(|(a, b)| Some((a.as_ref()?.mask, b.as_ref()?.mask))).collect();
pairs.iter().map(|(a, b)| (a - b).abs()).sum::<f32>() / pairs.len().max(1) as f32
}
/// Mean mask value over the pixels a preview sees
fn mean_mask(pixels: &[Option<MaskPreviewPixel>]) -> f32 {
pixels.iter().flatten().map(|pixel| pixel.mask).sum::<f32>() / pixels.iter().flatten().count().max(1) as f32
}
#[test]
fn invalid_preview_sizes_are_rejected_before_changing_the_shape() {
let session = Session::new_project("Orb preview", primitives::cube(2.0), "builtin:cube", None, 128).unwrap();
let layer = session.doc.project.texture_set(SET).unwrap().stack[0];
let bare = (session.doc.clone(), session.selected.clone());
let mut preview = OrbPreview { session, layer, bare, cameras: Vec::new() };
let stack_size = preview.session.doc.project.texture_set(SET).unwrap().stack.len();
for size in [0, MAX_PREVIEW_SIZE_PX + 1, usize::MAX / 2 + 1, usize::MAX] {
assert!(preview.mask("edges_sharp", size).is_none(), "size {size} should be rejected before rendering");
assert!(preview.material("steel_painted_worn", size).is_none(), "size {size} should be rejected before rendering");
assert!(preview.cameras.is_empty(), "invalid sizes must not allocate a camera");
assert!(preview.session.doc.project.layer(layer).unwrap().mask.is_none(), "invalid sizes must not apply a mask");
assert_eq!(preview.session.doc.project.texture_set(SET).unwrap().stack.len(), stack_size, "invalid sizes must not apply a material");
}
}
#[test]
fn smart_mask_previews_are_in_range_tell_edges_from_cavities_and_render_at_any_size() {
let size = 24;
let mut preview = OrbPreview::new().unwrap();
for smart_mask in crate::smart_masks::SMART_MASKS {
let id = smart_mask.id;
let pixels = preview.mask(id, size).unwrap_or_else(|| panic!("{id}"));
assert_eq!(pixels.len(), size * size, "{id}");
assert!(pixels[0].is_none(), "{id}: the corners are outside the shape");
let seen: Vec<&MaskPreviewPixel> = pixels.iter().flatten().collect();
assert!(seen.len() > size * size / 3, "{id}: the shape fills the frame");
for pixel in seen {
assert!((0.0..=1.0).contains(&pixel.mask) && (0.0..=1.0).contains(&pixel.coverage) && pixel.coverage > 0.0, "{id}: {pixel:?}");
assert!(pixel.normal.is_finite(), "{id}: {pixel:?}");
}
}
let (edges, cavities) = (preview.mask("edges_sharp", size).unwrap(), preview.mask("dirt_cavities", size).unwrap());
let shows = |pixels: &[Option<MaskPreviewPixel>]| pixels.iter().flatten().any(|pixel| pixel.mask > 0.5);
assert!(shows(&edges) && shows(&cavities), "both masks find something on the shape");
assert!(difference(&edges, &cavities) > 0.05, "edges and cavities differ: {}", difference(&edges, &cavities));
assert!(preview.mask("nope", size).is_none());
// The same bake renders other sizes, showing the same mask
let big = preview.mask("edges_sharp", size * 3).unwrap();
assert_eq!(big.len(), size * size * 9);
assert!((mean_mask(&big) - mean_mask(&edges)).abs() < 0.05, "{} vs {}", mean_mask(&big), mean_mask(&edges));
preview.mask("edges_sharp", size * 2).unwrap();
assert_eq!(preview.cameras.len(), CAMERAS_KEPT, "only the most recent sizes keep their camera");
}
#[test]
fn smart_materials_render_on_the_orb_and_show_their_wear() {
let size = 24;
let mut preview = OrbPreview::new().unwrap();
for material in materials::MATERIALS.iter().filter(|material| material.smart) {
let id = material.id;
let pixels = preview.material(id, size).unwrap_or_else(|| panic!("{id}"));
assert_eq!(pixels.len(), size * size, "{id}");
assert!(pixels[0].is_none(), "{id}: the corners are outside the shape");
for pixel in pixels.iter().flatten() {
let sample = pixel.sample;
let values = sample.base.into_iter().chain([sample.metallic, sample.roughness, sample.height]);
assert!(values.into_iter().all(f32::is_finite), "{id}: {pixel:?}");
assert!(pixel.normal.is_finite() && pixel.coverage > 0.0, "{id}: {pixel:?}");
}
}
assert!(preview.material("nope", size).is_none());
// Paint chipped at the edges shows the steel under it: the smart material is not its base
let (worn, steel) = (preview.material("steel_painted_worn", size).unwrap(), preview.material("steel", size).unwrap());
let metallic_pixels = |pixels: &[Option<MaterialPreviewPixel>]| pixels.iter().flatten().filter(|pixel| pixel.sample.metallic > 0.5).count();
let (worn_metallic, steel_metallic) = (metallic_pixels(&worn), metallic_pixels(&steel));
assert!(worn_metallic > 0 && worn_metallic < steel_metallic / 2, "bare steel only at the worn edges: {worn_metallic} of {steel_metallic}");
let base_colors = |pixels: &[Option<MaterialPreviewPixel>]| pixels.iter().flatten().map(|pixel| pixel.sample.base).collect::<Vec<_>>();
assert_ne!(base_colors(&worn), base_colors(&steel));
// Each material starts from the bare orb: rendering another one in between changes nothing
preview.material("iron_rusted", size).unwrap();
assert_eq!(preview.material("steel_painted_worn", size).unwrap(), worn);
}
}
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.