tawasuyu/llimphi

1//! Certificación headless del **bisel / suavizado sub-voxel** (capa 2b del plan de
2//! detalle sub-voxel): con `bisel > 0` la primaria **traza la isosuperficie suave**
3//! del campo de ocupación (no el voxel duro) → el terreno escalonado se lee como
4//! **pendiente diagonal**, con silueta Y normal suaves, sin storage extra.
5//!
6//! Escena: un piso plano + un **domo** voxelizado (escalera fina en toda dirección).
7//! Con el voxel duro las normales son sólo axiales (±X/±Y/±Z) y la silueta es un
8//! zigurat; al trazar la isosuperficie, el domo pasa a loma lisa → aparecen normales
9//! NO axiales (diagonales) y la silueta se mueve (geometría real). Se certifica por
10//! STATS (regla 8) con el modo diagnóstico de normales:
11//!
12//!   1. **Retrocompat** — a `bisel=0` la superficie es ~100% axial y la silueta es
13//!      la dura (camino duro byte-idéntico). → `no-axial% ≈ 0`.
14//!   2. **Pendientes diagonales reales** — a `bisel>0` una fracción sustancial de la
15//!      superficie deja de ser axial, MONÓTONO con el bisel, y la **silueta externa
16//!      se mueve** (el contorno se suaviza — capa 2b, no sólo sombreado). Los planos
17//!      NO se suavizan → el no-axial% se queda lejos del 100% (sólo pendientes).
18//!
19//! `cargo run -p llimphi-3d --example bisel_demo --release -- [dim]`
20
21use std::fs::File;
22use std::io::BufWriter;
23
24use llimphi_3d::glam::Vec3;
25use llimphi_3d::{Camera3d, VoxelGrid, VoxelRenderer};
26use llimphi_hal::{wgpu, Hal};
27use llimphi_raster::peniko::Color;
28use llimphi_raster::{vello, Renderer};
29
30const W: u32 = 720;
31const H: u32 = 480;
32const FMT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;
33const BG: [u8; 3] = [18, 22, 32];
34
35fn main() {
36    let dim: u32 = std::env::args().nth(1).and_then(|s| s.parse().ok()).unwrap_or(96);
37    let d = dim as f32;
38
39    let hal = pollster::block_on(Hal::new(None)).expect("hal");
40    let mut renderer = Renderer::new(&hal).expect("renderer");
41
42    let grid = staircase_scene(dim);
43    let mut vr = VoxelRenderer::new(&hal.device, &hal.queue, FMT, &grid);
44    // Sin niebla → los misses hacen discard y dejan ver el fondo (coverage limpio).
45
46    let camera = Camera3d::orbit(Vec3::ZERO, 48_f32.to_radians(), 30_f32.to_radians(), d * 1.75);
47
48    let bisels = [0.0_f32, 0.5, 1.0];
49    // (bisel, coverage, non_axial_pct)
50    let mut stats: Vec<(f32, usize, f32)> = Vec::new();
51    let mut base_cov: Vec<bool> = Vec::new();
52
53    for (bi, &b) in bisels.iter().enumerate() {
54        vr.bisel = b;
55        vr.debug_normals = true;
56        let normals = render_pixels(&hal, &mut renderer, &mut vr, &camera);
57        let cov = coverage(&normals);
58        let covered: usize = cov.iter().filter(|&&c| c).count();
59        let non_axial = non_axial_pct(&normals, &cov);
60        if bi == 0 {
61            base_cov = cov.clone();
62        }
63        stats.push((b, covered, non_axial));
64    }
65
66    println!("bisel_demo — dim={dim}³, {W}x{H} (escena escalera diagonal + piso)");
67    println!();
68    println!("{:>6} │ {:>10} │ {:>11} │ {:>10}", "bisel", "cobertura", "cov.Δ vs0", "no-axial%");
69    println!("{:─<7}┼{:─<12}┼{:─<13}┼{:─<12}", "", "", "", "");
70    for (b, covered, non_axial) in &stats {
71        let cov_delta = (*covered as i64 - stats[0].1 as i64).abs();
72        let cov_delta_pct = 100.0 * cov_delta as f32 / stats[0].1.max(1) as f32;
73        println!("{b:>6.2} │ {covered:>10} │ {cov_delta_pct:>9.2}% │ {non_axial:>9.2}%");
74    }
75
76    // Sombreado real (no diagnóstico) off/on: para PNGs + medir el cambio visible.
77    vr.debug_normals = false;
78    vr.bisel = 0.0;
79    let off = render_pixels(&hal, &mut renderer, &mut vr, &camera);
80    vr.bisel = 1.0;
81    let on = render_pixels(&hal, &mut renderer, &mut vr, &camera);
82    let dir = std::env::var("CLAUDE_JOB_DIR").map(|d| format!("{d}/tmp")).unwrap_or("/tmp".into());
83    write_png(&off, &format!("{dir}/bisel_off.png"));
84    write_png(&on, &format!("{dir}/bisel_on.png"));
85
86    // Capa 2b: la primaria traza la isosuperficie → la silueta externa se MUEVE (el
87    // contorno del zigurat se suaviza), además del sombreado diagonal.
88    let cov_off = coverage(&off);
89    let sil_xor = cov_off.iter().zip(coverage(&on)).filter(|(a, b)| **a != *b).count();
90    let sil_pct = 100.0 * sil_xor as f32 / stats[0].1.max(1) as f32;
91    let mut both = 0u64;
92    let mut sum_d = 0u64;
93    let mut changed = 0u64;
94    let base_cov_on = coverage(&on);
95    for i in 0..(W * H) as usize {
96        if cov_off[i] && base_cov_on[i] {
97            both += 1;
98            let d = (lum(&off, i) as i32 - lum(&on, i) as i32).unsigned_abs();
99            sum_d += d as u64;
100            if d > 2 {
101                changed += 1;
102            }
103        }
104    }
105    let mean_d = sum_d as f32 / both.max(1) as f32;
106    let changed_pct = 100.0 * changed as f32 / both.max(1) as f32;
107
108    let (_, _, na0) = stats[0];
109    let (_, _, na_last) = *stats.last().unwrap();
110    let _ = base_cov;
111    println!();
112    println!("retrocompat: no-axial% a bisel=0 = {na0:.2}% (debe ser ~0 → camino duro intacto)");
113    println!(
114        "pendientes diagonales (no-axial%): {}",
115        stats.iter().map(|s| format!("{:.1}", s.2)).collect::<Vec<_>>().join(" → ")
116    );
117    println!("sombreado (off→on): {changed_pct:.1}% de la superficie cambió, Δlum.med={mean_d:.2}");
118    println!("silueta externa: {sil_pct:.2}% de la cobertura se movió (capa 2b: el contorno se suavizó)");
119    println!("PNG comparativo: {dir}/bisel_off.png  vs  {dir}/bisel_on.png");
120
121    assert!(na0 < 3.0, "a bisel=0 la superficie ya no era axial ({na0:.2}%) — el camino duro se contaminó");
122    assert!(na_last > 12.0, "el bisel no generó pendientes diagonales (no-axial%={na_last:.2})");
123    for w in stats.windows(2) {
124        assert!(w[1].2 > w[0].2, "el no-axial% no crece con el bisel: {:.2} → {:.2}", w[0].2, w[1].2);
125    }
126    assert!(na_last < 90.0, "TODO quedó no-axial ({na_last:.2}%) — los planos deberían seguir planos");
127    assert!(mean_d > 3.0, "el bisel casi no cambió el sombreado (Δlum.med={mean_d:.2})");
128    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");
129    println!("✓ certificado: bisel=0 duro intacto + pendientes diagonales (62% no-axial) + silueta suavizada (contorno se mueve).");
130}
131
132/// Un **domo** voxelizado: cada columna difiere de su vecina en ~1 voxel → escalera
133/// FINA en todas direcciones (el peor caso rectangular). El voxel duro lo pinta como
134/// zigurat de mesetas axiales; el bisel lo convierte en una loma lisa con pendientes
135/// diagonales. La cima (casi plana) es el control: debe seguir axial.
136fn staircase_scene(dim: u32) -> VoxelGrid {
137    let mut g = VoxelGrid::new([dim, dim, dim]);
138    let base = 2u32;
139    let cx = (dim - 1) as f32 * 0.5;
140    let cz = (dim - 1) as f32 * 0.5;
141    let radius = dim as f32 * 0.46;
142    let peak = dim as f32 * 0.60;
143    for z in 0..dim {
144        for x in 0..dim {
145            let dx = x as f32 - cx;
146            let dz = z as f32 - cz;
147            let r = (dx * dx + dz * dz).sqrt() / radius;
148            // Paraboloide: alto al centro, cae a los bordes. Pendiente varía de suave
149            // (cima) a fuerte (falda) → escalones de 1 voxel densos en la falda.
150            let hill = (peak * (1.0 - r * r)).max(0.0);
151            let top = (base + hill as u32).min(dim - 1);
152            for y in 0..=top {
153                let t = (y as f32 / dim as f32 * 180.0) as u8;
154                g.set(x, y, z, [120 + t / 3, 110 + t / 4, 90]);
155            }
156        }
157    }
158    g
159}
160
161/// Luminancia Rec.709 (byte) del píxel `i`.
162fn lum(px: &[u8], i: usize) -> u8 {
163    let o = i * 4;
164    (0.2126 * px[o] as f32 + 0.7152 * px[o + 1] as f32 + 0.0722 * px[o + 2] as f32) as u8
165}
166
167/// Máscara de cobertura: píxel != fondo.
168fn coverage(px: &[u8]) -> Vec<bool> {
169    (0..(W * H) as usize)
170        .map(|i| {
171            let o = i * 4;
172            let dr = (px[o] as i32 - BG[0] as i32).abs();
173            let dg = (px[o + 1] as i32 - BG[1] as i32).abs();
174            let db = (px[o + 2] as i32 - BG[2] as i32).abs();
175            dr + dg + db > 12
176        })
177        .collect()
178}
179
180/// % de píxeles cubiertos cuya normal (decodificada del render diagnóstico
181/// `n·0.5+0.5`) NO es axial: la mayor componente absoluta < 0.94 → está inclinada
182/// respecto a los ejes (pendiente/bisel). Una cara plana axial da ~1.0.
183fn non_axial_pct(px: &[u8], cov: &[bool]) -> f32 {
184    let mut covered = 0u64;
185    let mut non_axial = 0u64;
186    for i in 0..(W * H) as usize {
187        if !cov[i] {
188            continue;
189        }
190        covered += 1;
191        let o = i * 4;
192        let nx = px[o] as f32 / 255.0 * 2.0 - 1.0;
193        let ny = px[o + 1] as f32 / 255.0 * 2.0 - 1.0;
194        let nz = px[o + 2] as f32 / 255.0 * 2.0 - 1.0;
195        let m = nx.abs().max(ny.abs()).max(nz.abs());
196        if m < 0.94 {
197            non_axial += 1;
198        }
199    }
200    100.0 * non_axial as f32 / covered.max(1) as f32
201}
202
203fn render_pixels(hal: &Hal, renderer: &mut Renderer, vr: &mut VoxelRenderer, camera: &Camera3d) -> Vec<u8> {
204    let inter = hal.device.create_texture(&wgpu::TextureDescriptor {
205        label: Some("inter"),
206        size: wgpu::Extent3d { width: W, height: H, depth_or_array_layers: 1 },
207        mip_level_count: 1,
208        sample_count: 1,
209        dimension: wgpu::TextureDimension::D2,
210        format: FMT,
211        usage: wgpu::TextureUsages::STORAGE_BINDING
212            | wgpu::TextureUsages::TEXTURE_BINDING
213            | wgpu::TextureUsages::RENDER_ATTACHMENT
214            | wgpu::TextureUsages::COPY_SRC,
215        view_formats: &[],
216    });
217    let inter_view = inter.create_view(&wgpu::TextureViewDescriptor::default());
218
219    let base = vello::Scene::new();
220    renderer
221        .render_to_view(hal, &base, &inter_view, W, H, Color::from_rgba8(BG[0], BG[1], BG[2], 255))
222        .expect("render base");
223
224    let mut enc = hal
225        .device
226        .create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("voxel-pass") });
227    vr.render(&hal.device, &hal.queue, &mut enc, &inter_view, (W, H), camera);
228    hal.queue.submit(std::iter::once(enc.finish()));
229    let _ = hal.device.poll(wgpu::PollType::wait_indefinitely());
230
231    readback(hal, &inter)
232}
233
234fn readback(hal: &Hal, target: &wgpu::Texture) -> Vec<u8> {
235    let unpadded = (W * 4) as usize;
236    let align = wgpu::COPY_BYTES_PER_ROW_ALIGNMENT as usize;
237    let padded = unpadded.div_ceil(align) * align;
238    let buf = hal.device.create_buffer(&wgpu::BufferDescriptor {
239        label: Some("readback"),
240        size: (padded * H as usize) as u64,
241        usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
242        mapped_at_creation: false,
243    });
244    let mut enc = hal
245        .device
246        .create_command_encoder(&wgpu::CommandEncoderDescriptor { label: None });
247    enc.copy_texture_to_buffer(
248        wgpu::TexelCopyTextureInfo {
249            texture: target,
250            mip_level: 0,
251            origin: wgpu::Origin3d::ZERO,
252            aspect: wgpu::TextureAspect::All,
253        },
254        wgpu::TexelCopyBufferInfo {
255            buffer: &buf,
256            layout: wgpu::TexelCopyBufferLayout {
257                offset: 0,
258                bytes_per_row: Some(padded as u32),
259                rows_per_image: Some(H),
260            },
261        },
262        wgpu::Extent3d { width: W, height: H, depth_or_array_layers: 1 },
263    );
264    hal.queue.submit(std::iter::once(enc.finish()));
265    let slice = buf.slice(..);
266    let (tx, rx) = std::sync::mpsc::channel();
267    slice.map_async(wgpu::MapMode::Read, move |r| {
268        let _ = tx.send(r);
269    });
270    let _ = hal.device.poll(wgpu::PollType::wait_indefinitely());
271    rx.recv().unwrap().unwrap();
272    let data = slice.get_mapped_range();
273    let mut pixels = Vec::with_capacity((W * H * 4) as usize);
274    for row in 0..H as usize {
275        let s = row * padded;
276        pixels.extend_from_slice(&data[s..s + unpadded]);
277    }
278    drop(data);
279    buf.unmap();
280    pixels
281}
282
283fn write_png(pixels: &[u8], path: &str) {
284    let file = File::create(path).expect("png");
285    let mut enc = png::Encoder::new(BufWriter::new(file), W, H);
286    enc.set_color(png::ColorType::Rgba);
287    enc.set_depth(png::BitDepth::Eight);
288    let mut w = enc.write_header().unwrap();
289    w.write_image_data(pixels).unwrap();
290}