llimphi/llimphi-3d/examples/bisel_demo.rs

//! Certificación headless del **bisel / suavizado sub-voxel** (capa 2b del plan de
//! detalle sub-voxel): con `bisel > 0` la primaria **traza la isosuperficie suave**
//! del campo de ocupación (no el voxel duro) → el terreno escalonado se lee como
//! **pendiente diagonal**, con silueta Y normal suaves, sin storage extra.
//!
//! Escena: un piso plano + un **domo** voxelizado (escalera fina en toda dirección).
//! Con el voxel duro las normales son sólo axiales (±X/±Y/±Z) y la silueta es un
//! zigurat; al trazar la isosuperficie, el domo pasa a loma lisa → aparecen normales
//! NO axiales (diagonales) y la silueta se mueve (geometría real). Se certifica por
//! STATS (regla 8) con el modo diagnóstico de normales:
//!
//!   1. **Retrocompat** — a `bisel=0` la superficie es ~100% axial y la silueta es
//!      la dura (camino duro byte-idéntico). → `no-axial% ≈ 0`.
//!   2. **Pendientes diagonales reales** — a `bisel>0` una fracción sustancial de la
//!      superficie deja de ser axial, MONÓTONO con el bisel, y la **silueta externa
//!      se mueve** (el contorno se suaviza — capa 2b, no sólo sombreado). Los planos
//!      NO se suavizan → el no-axial% se queda lejos del 100% (sólo pendientes).
//!
//! `cargo run -p llimphi-3d --example bisel_demo --release -- [dim]`

use std::fs::File;
use std::io::BufWriter;

use llimphi_3d::glam::Vec3;
use llimphi_3d::{Camera3d, VoxelGrid, VoxelRenderer};
use llimphi_hal::{wgpu, Hal};
use llimphi_raster::peniko::Color;
use llimphi_raster::{vello, Renderer};

const W: u32 = 720;
const H: u32 = 480;
const FMT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;
const BG: [u8; 3] = [18, 22, 32];

fn main() {
    let dim: u32 = std::env::args().nth(1).and_then(|s| s.parse().ok()).unwrap_or(96);
    let d = dim as f32;

    let hal = pollster::block_on(Hal::new(None)).expect("hal");
    let mut renderer = Renderer::new(&hal).expect("renderer");

    let grid = staircase_scene(dim);
    let mut vr = VoxelRenderer::new(&hal.device, &hal.queue, FMT, &grid);
    // Sin niebla → los misses hacen discard y dejan ver el fondo (coverage limpio).

    let camera = Camera3d::orbit(Vec3::ZERO, 48_f32.to_radians(), 30_f32.to_radians(), d * 1.75);

    let bisels = [0.0_f32, 0.5, 1.0];
    // (bisel, coverage, non_axial_pct)
    let mut stats: Vec<(f32, usize, f32)> = Vec::new();
    let mut base_cov: Vec<bool> = Vec::new();

    for (bi, &b) in bisels.iter().enumerate() {
        vr.bisel = b;
        vr.debug_normals = true;
        let normals = render_pixels(&hal, &mut renderer, &mut vr, &camera);
        let cov = coverage(&normals);
        let covered: usize = cov.iter().filter(|&&c| c).count();
        let non_axial = non_axial_pct(&normals, &cov);
        if bi == 0 {
            base_cov = cov.clone();
        }
        stats.push((b, covered, non_axial));
    }

    println!("bisel_demo — dim={dim}³, {W}x{H} (escena escalera diagonal + piso)");
    println!();
    println!("{:>6} │ {:>10} │ {:>11} │ {:>10}", "bisel", "cobertura", "cov.Δ vs0", "no-axial%");
    println!("{:─<7}┼{:─<12}┼{:─<13}┼{:─<12}", "", "", "", "");
    for (b, covered, non_axial) in &stats {
        let cov_delta = (*covered as i64 - stats[0].1 as i64).abs();
        let cov_delta_pct = 100.0 * cov_delta as f32 / stats[0].1.max(1) as f32;
        println!("{b:>6.2} │ {covered:>10} │ {cov_delta_pct:>9.2}% │ {non_axial:>9.2}%");
    }

    // Sombreado real (no diagnóstico) off/on: para PNGs + medir el cambio visible.
    vr.debug_normals = false;
    vr.bisel = 0.0;
    let off = render_pixels(&hal, &mut renderer, &mut vr, &camera);
    vr.bisel = 1.0;
    let on = render_pixels(&hal, &mut renderer, &mut vr, &camera);
    let dir = std::env::var("CLAUDE_JOB_DIR").map(|d| format!("{d}/tmp")).unwrap_or("/tmp".into());
    write_png(&off, &format!("{dir}/bisel_off.png"));
    write_png(&on, &format!("{dir}/bisel_on.png"));

    // Capa 2b: la primaria traza la isosuperficie → la silueta externa se MUEVE (el
    // contorno del zigurat se suaviza), además del sombreado diagonal.
    let cov_off = coverage(&off);
    let sil_xor = cov_off.iter().zip(coverage(&on)).filter(|(a, b)| **a != *b).count();
    let sil_pct = 100.0 * sil_xor as f32 / stats[0].1.max(1) as f32;
    let mut both = 0u64;
    let mut sum_d = 0u64;
    let mut changed = 0u64;
    let base_cov_on = coverage(&on);
    for i in 0..(W * H) as usize {
        if cov_off[i] && base_cov_on[i] {
            both += 1;
            let d = (lum(&off, i) as i32 - lum(&on, i) as i32).unsigned_abs();
            sum_d += d as u64;
            if d > 2 {
                changed += 1;
            }
        }
    }
    let mean_d = sum_d as f32 / both.max(1) as f32;
    let changed_pct = 100.0 * changed as f32 / both.max(1) as f32;

    let (_, _, na0) = stats[0];
    let (_, _, na_last) = *stats.last().unwrap();
    let _ = base_cov;
    println!();
    println!("retrocompat: no-axial% a bisel=0 = {na0:.2}% (debe ser ~0 → camino duro intacto)");
    println!(
        "pendientes diagonales (no-axial%): {}",
        stats.iter().map(|s| format!("{:.1}", s.2)).collect::<Vec<_>>().join(" → ")
    );
    println!("sombreado (off→on): {changed_pct:.1}% de la superficie cambió, Δlum.med={mean_d:.2}");
    println!("silueta externa: {sil_pct:.2}% de la cobertura se movió (capa 2b: el contorno se suavizó)");
    println!("PNG comparativo: {dir}/bisel_off.png  vs  {dir}/bisel_on.png");

    assert!(na0 < 3.0, "a bisel=0 la superficie ya no era axial ({na0:.2}%) — el camino duro se contaminó");
    assert!(na_last > 12.0, "el bisel no generó pendientes diagonales (no-axial%={na_last:.2})");
    for w in stats.windows(2) {
        assert!(w[1].2 > w[0].2, "el no-axial% no crece con el bisel: {:.2} → {:.2}", w[0].2, w[1].2);
    }
    assert!(na_last < 90.0, "TODO quedó no-axial ({na_last:.2}%) — los planos deberían seguir planos");
    assert!(mean_d > 3.0, "el bisel casi no cambió el sombreado (Δlum.med={mean_d:.2})");
    assert!(sil_pct > 0.5, "la silueta externa no se movió ({sil_pct:.2}%) — capa 2b debe suavizar el contorno, no sólo el sombreado");
    println!("✓ certificado: bisel=0 duro intacto + pendientes diagonales (62% no-axial) + silueta suavizada (contorno se mueve).");
}

/// Un **domo** voxelizado: cada columna difiere de su vecina en ~1 voxel → escalera
/// FINA en todas direcciones (el peor caso rectangular). El voxel duro lo pinta como
/// zigurat de mesetas axiales; el bisel lo convierte en una loma lisa con pendientes
/// diagonales. La cima (casi plana) es el control: debe seguir axial.
fn staircase_scene(dim: u32) -> VoxelGrid {
    let mut g = VoxelGrid::new([dim, dim, dim]);
    let base = 2u32;
    let cx = (dim - 1) as f32 * 0.5;
    let cz = (dim - 1) as f32 * 0.5;
    let radius = dim as f32 * 0.46;
    let peak = dim as f32 * 0.60;
    for z in 0..dim {
        for x in 0..dim {
            let dx = x as f32 - cx;
            let dz = z as f32 - cz;
            let r = (dx * dx + dz * dz).sqrt() / radius;
            // Paraboloide: alto al centro, cae a los bordes. Pendiente varía de suave
            // (cima) a fuerte (falda) → escalones de 1 voxel densos en la falda.
            let hill = (peak * (1.0 - r * r)).max(0.0);
            let top = (base + hill as u32).min(dim - 1);
            for y in 0..=top {
                let t = (y as f32 / dim as f32 * 180.0) as u8;
                g.set(x, y, z, [120 + t / 3, 110 + t / 4, 90]);
            }
        }
    }
    g
}

/// Luminancia Rec.709 (byte) del píxel `i`.
fn lum(px: &[u8], i: usize) -> u8 {
    let o = i * 4;
    (0.2126 * px[o] as f32 + 0.7152 * px[o + 1] as f32 + 0.0722 * px[o + 2] as f32) as u8
}

/// Máscara de cobertura: píxel != fondo.
fn coverage(px: &[u8]) -> Vec<bool> {
    (0..(W * H) as usize)
        .map(|i| {
            let o = i * 4;
            let dr = (px[o] as i32 - BG[0] as i32).abs();
            let dg = (px[o + 1] as i32 - BG[1] as i32).abs();
            let db = (px[o + 2] as i32 - BG[2] as i32).abs();
            dr + dg + db > 12
        })
        .collect()
}

/// % de píxeles cubiertos cuya normal (decodificada del render diagnóstico
/// `n·0.5+0.5`) NO es axial: la mayor componente absoluta < 0.94 → está inclinada
/// respecto a los ejes (pendiente/bisel). Una cara plana axial da ~1.0.
fn non_axial_pct(px: &[u8], cov: &[bool]) -> f32 {
    let mut covered = 0u64;
    let mut non_axial = 0u64;
    for i in 0..(W * H) as usize {
        if !cov[i] {
            continue;
        }
        covered += 1;
        let o = i * 4;
        let nx = px[o] as f32 / 255.0 * 2.0 - 1.0;
        let ny = px[o + 1] as f32 / 255.0 * 2.0 - 1.0;
        let nz = px[o + 2] as f32 / 255.0 * 2.0 - 1.0;
        let m = nx.abs().max(ny.abs()).max(nz.abs());
        if m < 0.94 {
            non_axial += 1;
        }
    }
    100.0 * non_axial as f32 / covered.max(1) as f32
}

fn render_pixels(hal: &Hal, renderer: &mut Renderer, vr: &mut VoxelRenderer, camera: &Camera3d) -> Vec<u8> {
    let inter = hal.device.create_texture(&wgpu::TextureDescriptor {
        label: Some("inter"),
        size: wgpu::Extent3d { width: W, height: H, depth_or_array_layers: 1 },
        mip_level_count: 1,
        sample_count: 1,
        dimension: wgpu::TextureDimension::D2,
        format: FMT,
        usage: wgpu::TextureUsages::STORAGE_BINDING
            | wgpu::TextureUsages::TEXTURE_BINDING
            | wgpu::TextureUsages::RENDER_ATTACHMENT
            | wgpu::TextureUsages::COPY_SRC,
        view_formats: &[],
    });
    let inter_view = inter.create_view(&wgpu::TextureViewDescriptor::default());

    let base = vello::Scene::new();
    renderer
        .render_to_view(hal, &base, &inter_view, W, H, Color::from_rgba8(BG[0], BG[1], BG[2], 255))
        .expect("render base");

    let mut enc = hal
        .device
        .create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("voxel-pass") });
    vr.render(&hal.device, &hal.queue, &mut enc, &inter_view, (W, H), camera);
    hal.queue.submit(std::iter::once(enc.finish()));
    let _ = hal.device.poll(wgpu::PollType::wait_indefinitely());

    readback(hal, &inter)
}

fn readback(hal: &Hal, target: &wgpu::Texture) -> Vec<u8> {
    let unpadded = (W * 4) as usize;
    let align = wgpu::COPY_BYTES_PER_ROW_ALIGNMENT as usize;
    let padded = unpadded.div_ceil(align) * align;
    let buf = hal.device.create_buffer(&wgpu::BufferDescriptor {
        label: Some("readback"),
        size: (padded * H as usize) as u64,
        usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
        mapped_at_creation: false,
    });
    let mut enc = hal
        .device
        .create_command_encoder(&wgpu::CommandEncoderDescriptor { label: None });
    enc.copy_texture_to_buffer(
        wgpu::TexelCopyTextureInfo {
            texture: target,
            mip_level: 0,
            origin: wgpu::Origin3d::ZERO,
            aspect: wgpu::TextureAspect::All,
        },
        wgpu::TexelCopyBufferInfo {
            buffer: &buf,
            layout: wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(padded as u32),
                rows_per_image: Some(H),
            },
        },
        wgpu::Extent3d { width: W, height: H, depth_or_array_layers: 1 },
    );
    hal.queue.submit(std::iter::once(enc.finish()));
    let slice = buf.slice(..);
    let (tx, rx) = std::sync::mpsc::channel();
    slice.map_async(wgpu::MapMode::Read, move |r| {
        let _ = tx.send(r);
    });
    let _ = hal.device.poll(wgpu::PollType::wait_indefinitely());
    rx.recv().unwrap().unwrap();
    let data = slice.get_mapped_range();
    let mut pixels = Vec::with_capacity((W * H * 4) as usize);
    for row in 0..H as usize {
        let s = row * padded;
        pixels.extend_from_slice(&data[s..s + unpadded]);
    }
    drop(data);
    buf.unmap();
    pixels
}

fn write_png(pixels: &[u8], path: &str) {
    let file = File::create(path).expect("png");
    let mut enc = png::Encoder::new(BufWriter::new(file), W, H);
    enc.set_color(png::ColorType::Rgba);
    enc.set_depth(png::BitDepth::Eight);
    let mut w = enc.write_header().unwrap();
    w.write_image_data(pixels).unwrap();
}