Offer three denoise networks and a method to choose between them

AI Denoise's Apply switch becomes Method: Bilinear, Fast, Medium, Best,
default Best, so an untouched raw writes nothing and develops through the
mixture. `apply` is still read and never written: 0 is Bilinear, 1 keeps
a network already chosen.

- Best is the mixture of a flat and an edge expert with a learned gate;
  Medium and Fast are students distilled from it. 2.48 s, 0.79 s and
  0.57 s for a 20 MP frame on TensorRT fp16.
- Each network carries its own tile border (256 for the mixture, 192 for
  the students) through `dr_denoise::Shipped` and `TileNet::halo`.
- The file is hashed once at open and each network keys its own cached
  result; Bilinear keeps the result in memory for the way back.
- Each has an .a16w16 sibling for the Hexagon: 0.00 dB on the 6D gate,
  at most 0.11 dB with the noise scaled x0.5 to x4.
- APK BUNDLED 19 -> 23; the PKGBUILD installs all three.

core/dr-denoise/examples/denoise_raw.rs

@@ -2,11 +2,11 @@
 //!
 //! ```sh
 //! DARKROOM_ORT_DIR=~/.local/share/darkroom/runtime \
-//!     cargo run --release -p dr-denoise --features native --example denoise_raw -- IMG.CR2 out
+//!     cargo run --release -p dr-denoise --features native --example denoise_raw -- IMG.CR2 out [fast|medium|best]
 //! ```
 //!
 //! Decode, the app's hot-pixel pass, the frame's noise from its best source,
-//! then the shipped network under the inference engine on whatever rung this
+//! then one of the shipped networks (`best` unless named) under the inference engine on whatever rung this
 //! machine probes to. Writes `out.npy` — the active area, `h×w×3` f32 linear
 //! camera RGB — for comparison with the training repo's own path
 //! (`tools/compare_rust.py` in darkroom-denoise). `DARKROOM_ORT_DIR` points
@@ -23,11 +23,21 @@ fn main() {
     env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("warn")).init();
     let mut args = std::env::args().skip(1);
     let (Some(input), Some(out)) = (args.next(), args.next()) else {
-        eprintln!("usage: denoise_raw RAW OUT_PREFIX");
+        eprintln!("usage: denoise_raw RAW OUT_PREFIX [fast|medium|best]");
         std::process::exit(2);
     };
-    let model =
-        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../models/denoise/mosaic-1408.onnx");
+    let shipped = match args.next().as_deref() {
+        None | Some("best") => dr_denoise::BEST,
+        Some("medium") => dr_denoise::MEDIUM,
+        Some("fast") => dr_denoise::FAST,
+        Some(other) => {
+            eprintln!("no network called {other}: fast, medium or best");
+            std::process::exit(2);
+        }
+    };
+    let model = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("../../models/denoise")
+        .join(shipped.file);
     let cache = std::env::var_os("DR_ENGINE_CACHE")
         .map(PathBuf::from)
         .unwrap_or_else(|| std::env::temp_dir().join("dr-denoise-engines"));
@@ -91,7 +101,7 @@ fn main() {
         noise.col
     );
 
-    let mut net = OnnxNet::from_path(&model).expect("model");
+    let mut net = OnnxNet::from_path(&model, shipped.halo).expect("model");
     println!(
         "rung          {}",
         net.rung().map(|r| r.label()).unwrap_or("?")

core/dr-denoise/src/lib.rs

@@ -27,6 +27,33 @@ use dr_decode::RawImage;
 pub use noise::{NoiseModel, Source};
 pub use tile::{TileNet, HALO};
 
+/// TRACES: FR-DEV-3g
+/// A network the app ships in `models/denoise/`: its file, and the context
+/// it needs past a tile's kept centre (docs/dev/denoise.md §13).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Shipped {
+    pub file: &'static str,
+    pub halo: usize,
+}
+
+/// The smallest student: 0.9 M parameters, 11 GMAC a megapixel.
+pub const FAST: Shipped = Shipped {
+    file: "mosaic-fast-1408.onnx",
+    halo: HALO,
+};
+/// A student of the mixture with the first release's shape: 3.2 M
+/// parameters, 48 GMAC a megapixel.
+pub const MEDIUM: Shipped = Shipped {
+    file: "mosaic-medium-1408.onnx",
+    halo: HALO,
+};
+/// The mixture: a flat expert, an edge expert and the gate that blends them.
+/// It reaches further than either, so it keeps a smaller centre of each tile.
+pub const BEST: Shipped = Shipped {
+    file: "mosaic-best-1408.onnx",
+    halo: 256,
+};
+
 #[derive(Debug, thiserror::Error)]
 pub enum DenoiseError {
     #[error("the network cannot take this photograph: {0}")]

core/dr-denoise/src/onnx.rs

@@ -21,15 +21,19 @@ pub const TILE: usize = 1408;
 pub struct OnnxNet {
     model: Model,
     tile: usize,
+    halo: usize,
 }
 
 impl OnnxNet {
-    pub fn from_path(path: &std::path::Path) -> Result<Self, DenoiseError> {
+    /// The network at `path`, which needs `halo` photosites of context
+    /// ([`crate::Shipped::halo`]).
+    pub fn from_path(path: &std::path::Path, halo: usize) -> Result<Self, DenoiseError> {
         let (path, form) = dr_inference_engine::resolve_model(Role::Denoiser, path);
         let bytes = std::fs::read(&path)?;
         Ok(OnnxNet {
             model: dr_inference_engine::open(Role::Denoiser, form, &bytes)?,
             tile: TILE,
+            halo,
         })
     }
 
@@ -44,6 +48,10 @@ impl TileNet for OnnxNet {
         self.tile
     }
 
+    fn halo(&self) -> usize {
+        self.halo
+    }
+
     fn run(
         &mut self,
         mosaic: Vec<f32>,

core/dr-denoise/src/tile.rs

@@ -15,7 +15,9 @@
 
 use dr_decode::CfaPattern;
 
-/// Photosites of context beyond a tile's kept centre, on every side.
+/// Photosites of context beyond a tile's kept centre, on every side, for a
+/// single network; a mixture reaches further and says so through
+/// [`TileNet::halo`].
 pub const HALO: usize = 192;
 
 /// A fixed-shape network: `mosaic` and `sigma`, `n×n` RGGB, in; `3×n×n`
@@ -28,6 +30,11 @@ pub const HALO: usize = 192;
 pub trait TileNet {
     /// The edge `n` of the square tile the network takes.
     fn tile(&self) -> usize;
+    /// Photosites of context it needs past a tile's kept centre: at least
+    /// its receptive field. [`HALO`] unless the network says otherwise.
+    fn halo(&self) -> usize {
+        HALO
+    }
     fn run(
         &mut self,
         mosaic: Vec<f32>,
@@ -78,13 +85,13 @@ pub fn run_tiled(
     let (dy, dx) = rggb_offset(pattern).ok_or_else(|| {
         crate::DenoiseError::Unsupported(format!("{pattern:?} is not a Bayer pattern"))
     })?;
-    let n = net.tile();
-    if n <= 2 * HALO || !(n - 2 * HALO).is_multiple_of(2) {
+    let (n, halo) = (net.tile(), net.halo());
+    if n <= 2 * halo || !(n - 2 * halo).is_multiple_of(2) {
         return Err(crate::DenoiseError::Model(format!(
-            "tile {n} leaves no even centre past a {HALO} halo"
+            "tile {n} leaves no even centre past a {halo} halo"
         )));
     }
-    let core = n - 2 * HALO;
+    let core = n - 2 * halo;
     // In unified coordinates the frame spans u ∈ [dy, dy + h), v ∈ [dx, dx + w).
     let (uh, uw) = (h + dy, w + dx);
     let (ty, tx) = (uh.div_ceil(core), uw.div_ceil(core));
@@ -108,11 +115,11 @@ pub fn run_tiled(
                 scope.spawn(move || {
                     for (i, (mrow, srow)) in m.chunks_mut(n).zip(s.chunks_mut(n)).enumerate() {
                         let r = chunk * rows_per + i;
-                        // Unified row u = u0 + r − HALO; frame row y = u − dy, reflected.
-                        let u = u0 as isize + r as isize - HALO as isize;
+                        // Unified row u = u0 + r − halo; frame row y = u − dy, reflected.
+                        let u = u0 as isize + r as isize - halo as isize;
                         let y = reflect(u - dy as isize, h);
                         for c in 0..n {
-                            let v = v0 as isize + c as isize - HALO as isize;
+                            let v = v0 as isize + c as isize - halo as isize;
                             let x = reflect(v - dx as isize, w);
                             let val = at(y, x);
                             mrow[c] = val;
@@ -169,10 +176,10 @@ pub fn run_tiled(
                             scope.spawn(move || {
                                 for (i, row) in block.chunks_mut(w * 3).enumerate() {
                                     let y = y_lo + chunk * per + i;
-                                    // Tile row of frame row y: u = y + dy = u0 + r − HALO.
-                                    let r = y + dy + HALO - u0;
+                                    // Tile row of frame row y: u = y + dy = u0 + r − halo.
+                                    let r = y + dy + halo - u0;
                                     for x in x_lo..x_hi {
-                                        let c = x + dx + HALO - v0;
+                                        let c = x + dx + halo - v0;
                                         for ch in 0..3 {
                                             row[x * 3 + ch] = rgb[ch * n * n + r * n + c];
                                         }

core/dr-pipeline/src/graph.rs

@@ -176,10 +176,10 @@ pub struct EditGraph {
     /// lens profile, so not in the state; it only decides whether the
     /// switch below is offered.
     denoise_available: bool,
-    /// Whether the learned denoise replaces the demosaic. An edit: published
-    /// as [`crate::learned_denoise`], captured, stored and undone with the
-    /// rest (FR-DEV-3c).
-    denoise_applied: bool,
+    /// Which demosaic develops the photograph: a network, or the classical
+    /// one. An edit: published as [`crate::learned_denoise`], captured,
+    /// stored and undone with the rest (FR-DEV-3c).
+    denoise_method: crate::learned_denoise::Method,
     /// How strongly to denoise, 0–100; what is not taken goes back as grain.
     denoise_strength: f32,
 }
@@ -239,7 +239,7 @@ impl EditGraph {
             lens_profile: None,
             lens_profile_applied: true,
             denoise_available: false,
-            denoise_applied: true,
+            denoise_method: crate::learned_denoise::Method::DEFAULT,
             denoise_strength: 100.0,
         }
     }
@@ -425,7 +425,13 @@ impl EditGraph {
     /// photograph that cannot take it is harmless and does nothing, as a
     /// lens switch with no profile does.
     pub fn denoise_applied(&self) -> bool {
-        self.denoise_applied
+        self.denoise_method.learned()
+    }
+
+    /// TRACES: FR-DEV-3g
+    /// Which demosaic is asked for.
+    pub fn denoise_method(&self) -> crate::learned_denoise::Method {
+        self.denoise_method
     }
 
     /// TRACES: FR-DEV-3g
@@ -625,7 +631,7 @@ impl EditGraph {
             OpCapability {
                 id: desc.id,
                 label: desc.label,
-                active: self.denoise_applied,
+                active: self.denoise_applied(),
                 params: desc
                     .params
                     .iter()
@@ -743,7 +749,7 @@ impl EditGraph {
             // Derived from the file, like the profile above.
             denoise_available: _,
             // Edits, in the state through `capabilities` like the lens switch.
-            denoise_applied: _,
+            denoise_method: _,
             denoise_strength: _,
             masks,
             film,
@@ -818,7 +824,19 @@ impl EditGraph {
     pub fn set_param(&mut self, op: OpId, param: ParamId, value: f32) {
         if op == crate::learned_denoise::ID {
             match param {
-                p if p == crate::learned_denoise::APPLY => self.denoise_applied = value != 0.0,
+                p if p == crate::learned_denoise::METHOD => {
+                    self.denoise_method = crate::learned_denoise::Method::from_index(value)
+                }
+                // 0.21 and 0.22's switch (see `APPLY`): off is the classical
+                // demosaic, on is a network — the one already chosen, if any.
+                p if p == crate::learned_denoise::APPLY => {
+                    use crate::learned_denoise::Method;
+                    if value == 0.0 {
+                        self.denoise_method = Method::Bilinear;
+                    } else if !self.denoise_method.learned() {
+                        self.denoise_method = Method::DEFAULT;
+                    }
+                }
                 p if p == crate::learned_denoise::STRENGTH => {
                     self.denoise_strength = value.clamp(0.0, 100.0)
                 }
@@ -889,8 +907,9 @@ impl EditGraph {
     pub fn param(&self, op: OpId, param: ParamId) -> Option<f32> {
         if op == crate::learned_denoise::ID {
             return match param {
+                p if p == crate::learned_denoise::METHOD => Some(self.denoise_method.index()),
                 p if p == crate::learned_denoise::APPLY => {
-                    Some(if self.denoise_applied { 1.0 } else { 0.0 })
+                    Some(if self.denoise_applied() { 1.0 } else { 0.0 })
                 }
                 p if p == crate::learned_denoise::STRENGTH => Some(self.denoise_strength),
                 p if p == crate::learned_denoise::GRAIN => Some(100.0 - self.denoise_strength),
@@ -943,9 +962,9 @@ impl EditGraph {
         // a reset does not change which lens took the photograph. What returns
         // to default is the answer to whether to use it, which is on.
         self.set_lens_profile_applied(true);
-        // The learned denoise returns to off; whether it is available is the
-        // file's and stays.
-        self.denoise_applied = true;
+        // The learned denoise returns to its default network; whether it is
+        // available is the file's and stays.
+        self.denoise_method = crate::learned_denoise::Method::DEFAULT;
         self.denoise_strength = 100.0;
     }
 
@@ -2106,9 +2125,14 @@ mod tests {
             .find(|c| c.id == learned_denoise::ID)
             .expect("offered");
         assert!(cap.active, "on by default");
+        assert_eq!(g.denoise_method(), learned_denoise::Method::Best);
         assert_eq!(g.denoise_grain(), 0.0, "at full strength");
         assert_eq!(cap.id, g.capabilities()[0].id, "and first in the panel");
-        g.set_param(learned_denoise::ID, learned_denoise::APPLY, 0.0);
+        g.set_param(
+            learned_denoise::ID,
+            learned_denoise::METHOD,
+            learned_denoise::Method::Bilinear.index(),
+        );
         g.set_param(learned_denoise::ID, learned_denoise::STRENGTH, 70.0);
         assert!(!g.denoise_applied());
         assert!((g.denoise_grain() - 0.3).abs() < 1e-6);
@@ -2117,6 +2141,58 @@ mod tests {
         assert_eq!(g.denoise_grain(), 0.0);
     }
 
+    #[test]
+    fn an_untouched_raw_writes_nothing_and_develops_through_the_best() {
+        // TRACES: FR-DEV-3g
+        use crate::learned_denoise::{self, Method};
+        let mut g = EditGraph::default_chain();
+        g.set_denoise_available(true);
+        assert_eq!(g.denoise_method(), Method::Best);
+        let stored = |g: &EditGraph| {
+            crate::Preset::capture_params(g)
+                .params()
+                .keys()
+                .any(|(op, _)| op == learned_denoise::ID.0)
+        };
+        assert!(!stored(&g), "the default is not written");
+        g.set_param(
+            learned_denoise::ID,
+            learned_denoise::METHOD,
+            Method::Fast.index(),
+        );
+        assert!(stored(&g), "a choice is");
+        assert!(
+            !crate::Preset::capture_params(&g).params().contains_key(&(
+                learned_denoise::ID.0.into(),
+                learned_denoise::APPLY.0.into()
+            )),
+            "and the old switch never is"
+        );
+    }
+
+    #[test]
+    fn an_edit_saved_with_the_switch_keeps_its_look() {
+        // TRACES: FR-DEV-3g
+        // 0.21 and 0.22 stored on or off; off is the classical demosaic, and
+        // on keeps a network already chosen.
+        use crate::learned_denoise::{self, Method};
+        let mut g = EditGraph::default_chain();
+        g.set_param(learned_denoise::ID, learned_denoise::APPLY, 0.0);
+        assert_eq!(g.denoise_method(), Method::Bilinear);
+        g.set_param(learned_denoise::ID, learned_denoise::APPLY, 1.0);
+        assert_eq!(g.denoise_method(), Method::DEFAULT);
+        g.set_param(
+            learned_denoise::ID,
+            learned_denoise::METHOD,
+            Method::Fast.index(),
+        );
+        g.set_param(learned_denoise::ID, learned_denoise::APPLY, 1.0);
+        assert_eq!(g.denoise_method(), Method::Fast);
+        // A number from a newer build with more methods is the default.
+        g.set_param(learned_denoise::ID, learned_denoise::METHOD, 9.0);
+        assert_eq!(g.denoise_method(), Method::DEFAULT);
+    }
+
     #[test]
     fn an_edit_saved_with_grain_keeps_its_look() {
         // TRACES: FR-DEV-3g
@@ -2137,11 +2213,16 @@ mod tests {
         let mut g = EditGraph::default_chain();
         g.set_denoise_available(true);
         g.set_param(learned_denoise::ID, learned_denoise::STRENGTH, 60.0);
+        g.set_param(
+            learned_denoise::ID,
+            learned_denoise::METHOD,
+            learned_denoise::Method::Medium.index(),
+        );
         let state = g.state();
         let mut h = EditGraph::default_chain();
         h.set_denoise_available(true);
         let _ = h.set_state(&state);
-        assert!(h.denoise_applied());
+        assert_eq!(h.denoise_method(), learned_denoise::Method::Medium);
         assert!((h.denoise_grain() - 0.4).abs() < 1e-6);
     }
 }

core/dr-pipeline/src/learned_denoise.rs

@@ -1,6 +1,6 @@
 //! TRACES: FR-DEV-3g
-//! The learned denoise's settings: whether to use it, and how much grain to
-//! keep.
+//! The learned denoise's settings: which network develops the photograph,
+//! if any, and how much grain to keep.
 //!
 //! Not an [`crate::operation::Operation`]: the learned stage replaces the
 //! demosaic and runs once per photograph, off the render path
@@ -17,6 +17,12 @@ use crate::descriptor::{Attribute, LocalizedKey, OpDescriptor, ParamDescriptor,
 use crate::{OpId, ParamId};
 
 pub const ID: OpId = OpId("learned_denoise");
+/// TRACES: FR-DEV-3g
+/// Which demosaic develops the photograph, a [`Method`] by index.
+pub const METHOD: ParamId = ParamId("method");
+/// What 0.21 and 0.22 stored instead of [`METHOD`]: on or off. Still read —
+/// off is [`Method::Bilinear`], on is the default network — so an edit saved
+/// by those releases keeps its look; never written, and not offered.
 pub const APPLY: ParamId = ParamId("apply");
 /// TRACES: FR-DEV-3g
 /// How strongly to denoise, 0–100: 100 is the network's result as it is, and
@@ -27,9 +33,52 @@ pub const STRENGTH: ParamId = ParamId("strength");
 /// written, and not offered as a control.
 pub const GRAIN: ParamId = ParamId("grain");
 
-/// On by default, at full strength: every Bayer raw is developed from the
-/// learned demosaic, and the switch and the slider are there to take it back
-/// or ease it off. It costs seconds per photograph the first time, while
+/// TRACES: FR-DEV-3g
+/// The demosaics a photograph can be developed with, in the order the
+/// sidecar numbers them. Three networks that trade time for quality — the
+/// same training, distilled into smaller students (docs/dev/denoise.md §13)
+/// — and the classical demosaic, which is no network at all.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Method {
+    /// The classical demosaic: the noise stays.
+    Bilinear,
+    /// The smallest student: a quarter of the medium network's work.
+    Fast,
+    /// One network the size of the first release's.
+    Medium,
+    /// Two experts, one for flat areas and one for edges, and a gate.
+    Best,
+}
+
+impl Method {
+    pub const ALL: [Method; 4] = [Method::Bilinear, Method::Fast, Method::Medium, Method::Best];
+    pub const DEFAULT: Method = Method::Best;
+
+    /// The sidecar's number for it.
+    pub fn index(self) -> f32 {
+        Self::ALL.iter().position(|m| *m == self).unwrap_or(0) as f32
+    }
+
+    /// The method a stored number names; out of range is the default, as
+    /// from a newer build with more of them.
+    pub fn from_index(value: f32) -> Method {
+        let i = value.round();
+        if i >= 0.0 && (i as usize) < Self::ALL.len() {
+            Self::ALL[i as usize]
+        } else {
+            Self::DEFAULT
+        }
+    }
+
+    /// Whether a network runs at all.
+    pub fn learned(self) -> bool {
+        self != Method::Bilinear
+    }
+}
+
+/// The best network by default, at full strength: every Bayer raw is
+/// developed from the learned demosaic, and the choice and the slider are
+/// there to take it back, trade it for time, or ease it off. It costs seconds per photograph the first time, while
 /// the classical demosaic shows; the result is cached, so a photograph
 /// reopened or exported does not pay again (docs/dev/denoise.md §7).
 pub(crate) static DESCRIPTOR: LazyLock<Arc<OpDescriptor>> = LazyLock::new(|| {
@@ -37,7 +86,17 @@ pub(crate) static DESCRIPTOR: LazyLock<Arc<OpDescriptor>> = LazyLock::new(|| {
         id: ID,
         label: LocalizedKey("op.learned_denoise"),
         params: vec![
-            ParamDescriptor::switch_on("apply", "param.learned_denoise.apply"),
+            ParamDescriptor::choice(
+                "method",
+                "param.learned_denoise.method",
+                vec![
+                    LocalizedKey("param.learned_denoise.method.bilinear"),
+                    LocalizedKey("param.learned_denoise.method.fast"),
+                    LocalizedKey("param.learned_denoise.method.medium"),
+                    LocalizedKey("param.learned_denoise.method.best"),
+                ],
+            )
+            .with_default(Method::DEFAULT.index()),
             ParamDescriptor::scalar(
                 "strength",
                 "param.learned_denoise.strength",