Debian Codegraph @

.cargo/vendor/av1-grain/src/create.rs

raw
1 // Copyright (c) 2022-2022, The rav1e contributors. All rights reserved
2 //
3 // This source code is subject to the terms of the BSD 2 Clause License and
4 // the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
5 // was not distributed with this source code in the LICENSE file, you can
6 // obtain it at www.aomedia.org/license/software. If the Alliance for Open
7 // Media Patent License 1.0 was not distributed with this source code in the
8 // PATENTS file, you can obtain it at www.aomedia.org/license/patent.
9
10 // The original work for this formula was implmented in aomenc, and this is
11 // an adaptation of that work:
12 // https://aomedia.googlesource.com/aom/+/refs/heads/main/examples/photon_noise_table.c
13
14 // This implementation creates a film grain table, for use in stills and videos,
15 // representing the noise that one would get by shooting with a digital camera
16 // at a given light level. Much of the noise in digital images is photon shot
17 // noise, which is due to the characteristics of photon arrival and grows in
18 // standard deviation as the square root of the expected number of photons
19 // captured.
20 // https://www.photonstophotos.net/Emil%20Martinec/noise.html#shotnoise
21 //
22 // The proxy used by this implementation for the amount of light captured
23 // is the ISO value such that the focal plane exposure at the time of capture
24 // would have been mapped by a 35mm camera to the output lightness observed
25 // in the image. That is, if one were to shoot on a 35mm camera (36×24mm sensor)
26 // at the nominal exposure for that ISO setting, the resulting image should
27 // contain noise of the same order of magnitude as generated by this
28 // implementation.
29 //
30 // The (mostly) square-root relationship between light intensity and noise
31 // amplitude holds in linear light, but AV1 streams are most often encoded
32 // non-linearly, and the film grain is applied to those non-linear values.
33 // Therefore, this implementation must account for the non-linearity, and this
34 // is controlled by the transfer function parameter, which specifies the tone
35 // response curve that will be used when encoding the actual image. The default
36 // for this implementation is BT.1886, which is approximately similar to an
37 // encoding gamma of 1/2.8 (i.e. a decoding gamma of 2.8) though not quite
38 // identical.
39 //
40 // As alluded to above, the implementation assumes that the image is taken from
41 // the entirety of a 36×24mm (“35mm format”) sensor. If that assumption does not
42 // hold, then a “35mm-equivalent ISO value” that can be passed to the
43 // implementation can be obtained by multiplying the true ISO value by the ratio
44 // of 36×24mm to the area that was actually used. For formats that approximately
45 // share the same aspect ratio, this is often expressed as the square of the
46 // “equivalence ratio” which is the ratio of their diagonals. For example, APS-C
47 // (often ~24×16mm) is said to have an equivalence ratio of 1.5 relative to the
48 // 35mm format, and therefore ISO 1000 on APS-C and ISO 1000×1.5² = 2250 on 35mm
49 // produce an image of the same lightness from the same amount of light spread
50 // onto their respective surface areas (resulting in different focal plane
51 // exposures), and those images will thus have similar amounts of noise if the
52 // cameras are of similar technology. https://doi.org/10.1117/1.OE.57.11.110801
53 //
54 // The implementation needs to know the resolution of the images to which its
55 // grain tables will be applied so that it can know how the light on the sensor
56 // was shared between its pixels. As a general rule, while a higher pixel count
57 // will lead to more noise per pixel, when the final image is viewed at the same
58 // physical size, that noise will tend to “average out” to the same amount over
59 // a given area, since there will be more pixels in it which, in aggregate, will
60 // have received essentially as much light. Put differently, the amount of noise
61 // depends on the scale at which it is measured, and the decision for this
62 // implementation was to make that scale relative to the image instead of its
63 // constituent samples. For more on this, see:
64 //
65 // https://www.photonstophotos.net/Emil%20Martinec/noise-p3.html#pixelsize
66 // https://www.dpreview.com/articles/5365920428/the-effect-of-pixel-and-sensor-sizes-on-noise/2
67 // https://www.dpreview.com/videos/7940373140/dpreview-tv-why-lower-resolution-sensors-are-not-better-in-low-light
68
69 use std::{
70 fs::File,
71 io::{BufWriter, Write},
72 path::Path,
73 };
74
75 use arrayvec::ArrayVec;
76
77 use crate::{GrainTableSegment, ScalingPoints, DEFAULT_GRAIN_SEED, NUM_Y_POINTS};
78
79 const PQ_M1: f32 = 2610. / 16384.;
80 const PQ_M2: f32 = 128. * 2523. / 4096.;
81 const PQ_C1: f32 = 3424. / 4096.;
82 const PQ_C2: f32 = 32. * 2413. / 4096.;
83 const PQ_C3: f32 = 32. * 2392. / 4096.;
84
85 const BT1886_WHITEPOINT: f32 = 203.;
86 const BT1886_BLACKPOINT: f32 = 0.1;
87 const BT1886_GAMMA: f32 = 2.4;
88
89 // BT.1886 formula from https://en.wikipedia.org/wiki/ITU-R_BT.1886.
90 //
91 // TODO: the inverses, alpha, and beta should all be constants
92 // once floats in const fns are stabilized and `powf` is const.
93 // Until then, `inline(always)` gets us close enough.
94
95 fn bt1886_inv_whitepoint() -> f32 {
96 BT1886_WHITEPOINT.powf(1.0 / BT1886_GAMMA)
97 }
98
99 fn bt1886_inv_blackpoint() -> f32 {
100 BT1886_BLACKPOINT.powf(1.0 / BT1886_GAMMA)
101 }
102
103 /// The variable for user gain:
104 /// `α = (Lw^(1/λ) - Lb^(1/λ)) ^ λ`
105 fn bt1886_alpha() -> f32 {
106 (bt1886_inv_whitepoint() - bt1886_inv_blackpoint()).powf(BT1886_GAMMA)
107 }
108
109 /// The variable for user black level lift:
110 /// `β = Lb^(1/λ) / (Lw^(1/λ) - Lb^(1/λ))`
111 fn bt1886_beta() -> f32 {
112 bt1886_inv_blackpoint() / (bt1886_inv_whitepoint() - bt1886_inv_blackpoint())
113 }
114
115 /// Settings and video data defining how to generate the film grain params.
116 #[derive(Debug, Clone, Copy)]
117 pub struct NoiseGenArgs {
118 pub iso_setting: u32,
119 pub width: u32,
120 pub height: u32,
121 pub transfer_function: TransferFunction,
122 pub chroma_grain: bool,
123 pub random_seed: Option<u16>,
124 }
125
126 /// Generates a set of photon noise parameters for a segment of video
127 /// given a set of `args`.
128 #[must_use]
129 #[inline]
130 pub fn generate_photon_noise_params(
131 start_time: u64,
132 end_time: u64,
133 args: NoiseGenArgs,
134 ) -> GrainTableSegment {
135 GrainTableSegment {
136 start_time,
137 end_time,
138 scaling_points_y: generate_luma_noise_points(args),
139 scaling_points_cb: ArrayVec::new(),
140 scaling_points_cr: ArrayVec::new(),
141 scaling_shift: 8,
142 ar_coeff_lag: 0,
143 ar_coeffs_y: ArrayVec::new(),
144 ar_coeffs_cb: ArrayVec::try_from([0].as_slice())
145 .expect("Cannot fail creation from const array"),
146 ar_coeffs_cr: ArrayVec::try_from([0].as_slice())
147 .expect("Cannot fail creation from const array"),
148 ar_coeff_shift: 6,
149 cb_mult: 0,
150 cb_luma_mult: 0,
151 cb_offset: 0,
152 cr_mult: 0,
153 cr_luma_mult: 0,
154 cr_offset: 0,
155 overlap_flag: true,
156 chroma_scaling_from_luma: args.chroma_grain,
157 grain_scale_shift: 0,
158 random_seed: args.random_seed.unwrap_or(DEFAULT_GRAIN_SEED),
159 }
160 }
161
162 /// Generates a set of film grain parameters for a segment of video
163 /// given a set of `args`.
164 ///
165 /// # Panics
166 /// - This is not yet implemented, so it will always panic
167 #[must_use]
168 #[inline]
169 #[cfg(feature = "unstable")]
170 pub fn generate_film_grain_params(
171 start_time: u64,
172 end_time: u64,
173 args: NoiseGenArgs,
174 ) -> GrainTableSegment {
175 todo!("SCIENCE");
176 // GrainTableSegment {
177 // start_time,
178 // end_time,
179 // scaling_points_y: generate_luma_noise_points(args),
180 // scaling_points_cb: ArrayVec::new(),
181 // scaling_points_cr: ArrayVec::new(),
182 // scaling_shift: 8,
183 // ar_coeff_lag: 0,
184 // ar_coeffs_y: ArrayVec::new(),
185 // ar_coeffs_cb: ArrayVec::try_from([0].as_slice())
186 // .expect("Cannot fail creation from const array"),
187 // ar_coeffs_cr: ArrayVec::try_from([0].as_slice())
188 // .expect("Cannot fail creation from const array"),
189 // ar_coeff_shift: 6,
190 // cb_mult: 0,
191 // cb_luma_mult: 0,
192 // cb_offset: 0,
193 // cr_mult: 0,
194 // cr_luma_mult: 0,
195 // cr_offset: 0,
196 // overlap_flag: true,
197 // chroma_scaling_from_luma: args.chroma_grain,
198 // grain_scale_shift: 0,
199 // random_seed: args.random_seed.unwrap_or(DEFAULT_GRAIN_SEED),
200 // }
201 }
202
203 /// Write a set of generated film grain params to a table file,
204 /// using the standard film grain table format supported by
205 /// aomenc, rav1e, and svt-av1.
206 ///
207 /// # Errors
208 ///
209 /// - If the output file cannot be written to
210 #[inline]
211 pub fn write_grain_table<P: AsRef<Path>>(
212 filename: P,
213 params: &[GrainTableSegment],
214 ) -> anyhow::Result<()> {
215 let mut file = BufWriter::new(File::create(filename)?);
216 writeln!(&mut file, "filmgrn1")?;
217 for segment in params {
218 write_film_grain_segment(segment, &mut file)?;
219 }
220 file.flush()?;
221
222 Ok(())
223 }
224
225 fn write_film_grain_segment(
226 params: &GrainTableSegment,
227 output: &mut BufWriter<File>,
228 ) -> anyhow::Result<()> {
229 writeln!(
230 output,
231 "E {} {} 1 {} 1",
232 params.start_time, params.end_time, params.random_seed,
233 )?;
234 writeln!(
235 output,
236 "\tp {} {} {} {} {} {} {} {} {} {} {} {}",
237 params.ar_coeff_lag,
238 params.ar_coeff_shift,
239 params.grain_scale_shift,
240 params.scaling_shift,
241 u8::from(params.chroma_scaling_from_luma),
242 u8::from(params.overlap_flag),
243 params.cb_mult,
244 params.cb_luma_mult,
245 params.cb_offset,
246 params.cr_mult,
247 params.cr_luma_mult,
248 params.cr_offset
249 )?;
250
251 write!(output, "\tsY {} ", params.scaling_points_y.len())?;
252 for point in &params.scaling_points_y {
253 write!(output, " {} {}", point[0], point[1])?;
254 }
255 writeln!(output)?;
256
257 write!(output, "\tsCb {}", params.scaling_points_cb.len())?;
258 for point in &params.scaling_points_cb {
259 write!(output, " {} {}", point[0], point[1])?;
260 }
261 writeln!(output)?;
262
263 write!(output, "\tsCr {}", params.scaling_points_cr.len())?;
264 for point in &params.scaling_points_cr {
265 write!(output, " {} {}", point[0], point[1])?;
266 }
267 writeln!(output)?;
268
269 write!(output, "\tcY")?;
270 for coeff in &params.ar_coeffs_y {
271 write!(output, " {}", *coeff)?;
272 }
273 writeln!(output)?;
274
275 write!(output, "\tcCb")?;
276 for coeff in &params.ar_coeffs_cb {
277 write!(output, " {}", *coeff)?;
278 }
279 writeln!(output)?;
280
281 write!(output, "\tcCr")?;
282 for coeff in &params.ar_coeffs_cr {
283 write!(output, " {}", *coeff)?;
284 }
285 writeln!(output)?;
286
287 Ok(())
288 }
289
290 #[allow(clippy::upper_case_acronyms)]
291 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
292 pub enum TransferFunction {
293 /// For SDR content
294 BT1886,
295 /// For HDR content
296 SMPTE2084,
297 }
298
299 impl TransferFunction {
300 #[must_use]
301 #[inline]
302 pub fn to_linear(self, x: f32) -> f32 {
303 match self {
304 TransferFunction::BT1886 => {
305 // The screen luminance in cd/m^2:
306 // L = α * (x + β)^λ
307 let luma = bt1886_alpha() * (x + bt1886_beta()).powf(BT1886_GAMMA);
308
309 // Normalize to between 0.0 and 1.0
310 luma / BT1886_WHITEPOINT
311 }
312 TransferFunction::SMPTE2084 => {
313 let pq_pow_inv_m2 = x.powf(1. / PQ_M2);
314 (0_f32.max(pq_pow_inv_m2 - PQ_C1) / PQ_C3.mul_add(-pq_pow_inv_m2, PQ_C2))
315 .powf(1. / PQ_M1)
316 }
317 }
318 }
319
320 #[allow(clippy::wrong_self_convention)]
321 #[must_use]
322 #[inline]
323 pub fn from_linear(self, x: f32) -> f32 {
324 match self {
325 TransferFunction::BT1886 => {
326 // Scale to a raw cd/m^2 value
327 let luma = x * BT1886_WHITEPOINT;
328
329 // The inverse of the `to_linear` formula:
330 // `(L / α)^(1 / λ) - β = x`
331 (luma / bt1886_alpha()).powf(1.0 / BT1886_GAMMA) - bt1886_beta()
332 }
333 TransferFunction::SMPTE2084 => {
334 if x < f32::EPSILON {
335 return 0.0;
336 }
337 let linear_pow_m1 = x.powf(PQ_M1);
338 (PQ_C2.mul_add(linear_pow_m1, PQ_C1) / PQ_C3.mul_add(linear_pow_m1, 1.)).powf(PQ_M2)
339 }
340 }
341 }
342
343 #[inline]
344 #[must_use]
345 pub fn mid_tone(self) -> f32 {
346 self.to_linear(0.5)
347 }
348 }
349
350 fn generate_luma_noise_points(args: NoiseGenArgs) -> ScalingPoints {
351 // Assumes a daylight-like spectrum.
352 // https://www.strollswithmydog.com/effective-quantum-efficiency-of-sensor/#:~:text=11%2C260%20photons/um%5E2/lx-s
353 const PHOTONS_PER_SQ_MICRON_PER_LUX_SECOND: f32 = 11260.;
354
355 // Order of magnitude for cameras in the 2010-2020 decade, taking the CFA into
356 // account.
357 const EFFECTIVE_QUANTUM_EFFICIENCY: f32 = 0.2;
358
359 // Also reasonable values for current cameras. The read noise is typically
360 // higher than this at low ISO settings but it matters less there.
361 const PHOTO_RESPONSE_NON_UNIFORMITY: f32 = 0.005;
362 const INPUT_REFERRED_READ_NOISE: f32 = 1.5;
363
364 // Assumes a 35mm sensor (36mm × 24mm).
365 const SENSOR_AREA: f32 = 36_000. * 24_000.;
366
367 // Focal plane exposure for a mid-tone (typically a 18% reflectance card), in
368 // lx·s.
369 let mid_tone_exposure = 10. / args.iso_setting as f32;
370
371 let pixel_area_microns = SENSOR_AREA / (args.width * args.height) as f32;
372
373 let mid_tone_electrons_per_pixel = EFFECTIVE_QUANTUM_EFFICIENCY
374 * PHOTONS_PER_SQ_MICRON_PER_LUX_SECOND
375 * mid_tone_exposure
376 * pixel_area_microns;
377 let max_electrons_per_pixel = mid_tone_electrons_per_pixel / args.transfer_function.mid_tone();
378
379 let mut scaling_points = ScalingPoints::default();
380 for i in 0..NUM_Y_POINTS {
381 let x = i as f32 / (NUM_Y_POINTS as f32 - 1.);
382 let linear = args.transfer_function.to_linear(x);
383 let electrons_per_pixel = max_electrons_per_pixel * linear;
384
385 // Quadrature sum of the relevant sources of noise, in electrons rms. Photon
386 // shot noise is sqrt(electrons) so we can skip the square root and the
387 // squaring.
388 // https://en.wikipedia.org/wiki/Addition_in_quadrature
389 // https://doi.org/10.1117/3.725073
390 let noise_in_electrons = (PHOTO_RESPONSE_NON_UNIFORMITY
391 * PHOTO_RESPONSE_NON_UNIFORMITY
392 * electrons_per_pixel)
393 .mul_add(
394 electrons_per_pixel,
395 INPUT_REFERRED_READ_NOISE.mul_add(INPUT_REFERRED_READ_NOISE, electrons_per_pixel),
396 )
397 .sqrt();
398 let linear_noise = noise_in_electrons / max_electrons_per_pixel;
399 let linear_range_start = 0_f32.max(2.0f32.mul_add(-linear_noise, linear));
400 let linear_range_end = 1_f32.min(2_f32.mul_add(linear_noise, linear));
401 let tf_slope = (args.transfer_function.from_linear(linear_range_end)
402 - args.transfer_function.from_linear(linear_range_start))
403 / (linear_range_end - linear_range_start);
404 let encoded_noise = linear_noise * tf_slope;
405
406 let x = (255. * x).round() as u8;
407 let encoded_noise = 255_f32.min((255. * 7.88 * encoded_noise).round()) as u8;
408
409 scaling_points.push([x, encoded_noise]);
410 }
411
412 scaling_points
413 }
414
415 #[cfg(test)]
416 mod tests {
417 use quickcheck::TestResult;
418 use quickcheck_macros::quickcheck;
419
420 use super::*;
421
422 #[quickcheck]
423 fn bt1886_to_linear_within_range(x: f32) -> TestResult {
424 if !(0.0..=1.0).contains(&x) || x.is_nan() {
425 return TestResult::discard();
426 }
427
428 let tx = TransferFunction::BT1886;
429 let res = tx.to_linear(x);
430 TestResult::from_bool((0.0..=1.0).contains(&res))
431 }
432
433 #[quickcheck]
434 fn bt1886_to_linear_reverts_correctly(x: f32) -> TestResult {
435 if !(0.0..=1.0).contains(&x) || x.is_nan() {
436 return TestResult::discard();
437 }
438
439 let tx = TransferFunction::BT1886;
440 let res = tx.to_linear(x);
441 let res = tx.from_linear(res);
442 TestResult::from_bool((x - res).abs() < f32::EPSILON)
443 }
444
445 #[quickcheck]
446 fn smpte2084_to_linear_within_range(x: f32) -> TestResult {
447 if !(0.0..=1.0).contains(&x) || x.is_nan() {
448 return TestResult::discard();
449 }
450
451 let tx = TransferFunction::SMPTE2084;
452 let res = tx.to_linear(x);
453 TestResult::from_bool((0.0..=1.0).contains(&res))
454 }
455
456 #[quickcheck]
457 fn smpte2084_to_linear_reverts_correctly(x: f32) -> TestResult {
458 if !(0.0..=1.0).contains(&x) || x.is_nan() {
459 return TestResult::discard();
460 }
461
462 let tx = TransferFunction::SMPTE2084;
463 let res = tx.to_linear(x);
464 let res = tx.from_linear(res);
465 TestResult::from_bool((x - res).abs() < f32::EPSILON)
466 }
467 }