Skip to main content

threers_probe/
lib.rs

1//! Screen-space neural GI from a G-buffer and a lighting probe.
2//!
3//! The path tracer is the teacher. At inference the network sees first-hit
4//! albedo, normal and depth, a multi-bounce lighting probe, quarter-res probe
5//! context, DDGI-lite world bins, and encoded hit positions. Heads: Direct
6//! irradiance residual, 7×7 kernel gather, hybrid (KPN + capped residual),
7//! hops (à-trous light jumps + world-grid teleport), plus an optional
8//! NRC-style 1×1 MLP for per-pixel world residuals. The training family
9//! includes jittered furnace-like shells so hops learn uniform-bright identity.
10//!
11//! Built from `conv2d` / `relu` / `concat` / a fixed 2× pool, so the same
12//! graph trains on Metal or CUDA and runs on the CPU the browser already has.
13
14pub mod checkpoint;
15pub mod dataset;
16pub mod ddgi;
17pub mod infer;
18pub mod live_cornell;
19pub mod model;
20pub mod nrc;
21pub mod pack;
22pub mod train;
23
24#[cfg(target_arch = "wasm32")]
25pub mod wasm;
26
27#[cfg(feature = "generate")]
28pub mod generate;
29
30pub use dataset::Dataset;
31pub use ddgi::{
32    bounds_from_world, encode_frame, encode_world_planes, DdgiContext, DDGI_GRID, DDGI_GRID_Y,
33    DDGI_VIS_PLANE,
34};
35pub use infer::{ProbeGi, ProbeNet};
36pub use model::{
37    init_params, Head, ProbeArch, Widths, ALBEDO_FLOOR, GRAPH_ROOM_TINT, HOPS_IRRADIANCE_CAP,
38    HYBRID_IRRADIANCE_CAP, IN_CHANNELS, OUT_CHANNELS,
39};
40pub use nrc::{
41    fuse_beauty, fuse_beauty_with, init_params as init_nrc_params, load_nrc, load_nrc_bytes,
42    mean_albedo, nrc_apply_mask, nrc_eligible, nrc_features, nrc_input_channels, pack_nrc_batch,
43    pack_nrc_batch_with, probe_colour_relative_sq, save_nrc, train_nrc, train_nrc_dataset,
44    train_nrc_from, NrcArch, NrcNet, HOPS_NRC_CAP, HOPS_NRC_PROBE_CONFIDENCE, NRC_CAP, NRC_IN,
45    NRC_IN_DDGI, NRC_MAX_PROBE, NRC_MIN_ALBEDO, NRC_OUT, NRC_PROBE_CONFIDENCE,
46};
47pub use pack::{
48    colour_planes, geometry_hits, planes, PlaneExtras, DEPTH_PLANE, SKY_DEPTH_COMPRESSED,
49};
50pub use train::{
51    Batch, TrainConfig, Trainer, GI_LOSS_BOOST, HOPS_CHROMA_LOSS_BOOST, HOPS_GI_LOSS_BOOST,
52    HOPS_NEUTRAL_LOSS_BOOST, LOSS_EPSILON, TRAIN_EPSILON,
53};
54
55use rlx::Device;
56
57/// The device this crate actually trains and infers on.
58///
59/// Metal when the `metal` feature is on and a device is present; otherwise the
60/// CPU. The GPU feature is rlx's wgpu, a different device from the renderer.
61pub fn preferred_device() -> Device {
62    #[cfg(feature = "metal")]
63    {
64        if rlx::is_available(Device::Metal) {
65            return Device::Metal;
66        }
67    }
68    #[cfg(feature = "gpu")]
69    {
70        if rlx::is_available(Device::Gpu) {
71            return Device::Gpu;
72        }
73    }
74    Device::Cpu
75}
76
77/// Compress unbounded radiance into `[0, 1)` for the convolution stack.
78///
79/// `x / (1 + x)` is monotone and invertible as [`expand`]. Non-finite values
80/// would poison every layer that touches them: +∞ is maximum energy (1),
81/// anything else (NaN, −∞) is 0.
82pub fn compress(v: f32) -> f32 {
83    if !v.is_finite() {
84        return if v > 0.0 { 1.0 } else { 0.0 };
85    }
86    (v.max(0.0) / (1.0 + v.max(0.0))).min(0.999)
87}
88
89/// Inverse of [`compress`]. Values at 1 (compressed infinity) stay large
90/// rather than dividing by zero.
91pub fn expand(v: f32) -> f32 {
92    let v = v.clamp(0.0, 0.999_999);
93    v / (1.0 - v)
94}
95
96#[cfg(test)]
97mod tests {
98    use super::*;
99
100    #[test]
101    fn compress_round_trips_finite_radiance() {
102        for v in [0.0, 0.01, 0.5, 1.0, 8.0, 100.0] {
103            let back = expand(compress(v));
104            assert!((back - v).abs() / v.max(1e-6) < 1e-5, "{v} -> {back}");
105        }
106        assert_eq!(compress(f32::INFINITY), 1.0);
107        assert_eq!(compress(f32::NAN), 0.0);
108        assert_eq!(compress(-3.0), 0.0);
109    }
110}