colorvideovdp/lib.rs
1//! A pure-Rust port of ColorVideoVDP, a full-reference visual difference
2//! predictor for images and video.
3//!
4//! ColorVideoVDP (the authors call it `cvvdp`) compares a test image or video
5//! with a reference, as seen on a specified display, and predicts the visible
6//! difference in Just-Objectionable-Difference (JOD) units. 10 JOD means no
7//! visible difference, and lower values mean stronger distortion; very strong
8//! distortions can give negative values. A difference of 1 JOD between two
9//! conditions means that 75% of observers would choose the one with the higher
10//! score. This crate implements the calibrated base model v0.5.7
11//! ([`Cvvdp::MODEL_VERSION`]) of the official PyTorch implementation.
12//!
13//! ```
14//! use colorvideovdp::{Color, Cvvdp, DisplayModel, Image, Options};
15//!
16//! # fn main() -> colorvideovdp::Result<()> {
17//! let reference = Image::new(16, 16, 3, vec![0.5; 16 * 16 * 3])?;
18//! let mut test = reference.clone();
19//! test.data_mut()[0] = 0.6;
20//!
21//! let metric = Cvvdp::new(DisplayModel::from_name("standard_4k")?, Options::default())?;
22//! let prediction = metric.predict_image(&test, &reference, Color::Srgb)?;
23//! assert!(prediction.jod < 10.0);
24//! # Ok(())
25//! # }
26//! ```
27//!
28//! # Algorithm
29//!
30//! 1. The display model maps encoded or linear input to absolute luminance
31//! (EOTF, peak luminance, black level, reflected ambient light), then to the
32//! DKL opponent space: achromatic, red–green, and yellow–violet.
33//! 2. For video, temporal filters split each frame into sustained channels and
34//! an achromatic transient channel.
35//! 3. Each channel is decomposed into a Laplacian pyramid and converted to
36//! contrast relative to the local background luminance.
37//! 4. Contrast is weighted by castleCSF sensitivity for each band's spatial
38//! frequency and the local luminance.
39//! 5. Test–reference differences are reduced by cross-channel masking, with a
40//! blur that models phase uncertainty, and soft-clamped.
41//! 6. Differences are pooled with Lp norms over space, bands, channels, and
42//! frames, and the pooled value is mapped to JOD.
43//!
44//! # Inputs and displays
45//!
46//! [`Image`] holds one f32 frame. Encoded inputs (sRGB, PQ, HLG, gamma) are
47//! clamped to [0, 1]; linear inputs are absolute luminance in cd/m². The
48//! [`DisplayModel`] sets resolution, viewing geometry, and photometry; the 26
49//! reference displays are embedded and listed by [`DisplayModel::names`].
50//!
51//! # Features
52//!
53//! - `parallel` (default): [`Execution::Parallel`] splits independent spatial
54//! rows across the Rayon thread pool. Results are identical to
55//! [`Execution::SingleThread`].
56//!
57//! # Reference
58//!
59//! Rafał K. Mantiuk, Param Hanji, Maliha Ashraf, Yuta Asano, and Alexandre
60//! Chapiro. ColorVideoVDP: A visual difference predictor for image, video and
61//! display distortions. In SIGGRAPH 2024 Technical Papers, Article 129.
62//! <https://doi.org/10.1145/3658144>
63//!
64//! The official implementation is <https://github.com/gfxdisp/ColorVideoVDP>.
65
66mod allocation;
67mod color;
68mod csf;
69mod display;
70mod error;
71mod image;
72mod metric;
73mod parameters;
74mod plane;
75mod pyramid;
76mod temporal;
77
78pub use display::{Color, DisplayModel, Geometry, Photometry};
79pub use error::{Error, Result};
80pub use image::Image;
81pub use metric::Cvvdp;
82
83/// Padding before the first video frame during temporal filtering.
84#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
85#[non_exhaustive]
86pub enum TemporalPadding {
87 /// Repeat the first frame (the reference default).
88 #[default]
89 Replicate,
90 /// Reflect without repeating the endpoints; short clips reflect repeatedly.
91 Symmetric,
92}
93
94/// CPU execution policy. Pooling order is deterministic in both modes.
95#[derive(Debug, Clone, Copy, PartialEq, Eq)]
96#[non_exhaustive]
97pub enum Execution {
98 /// Run all work on the calling thread.
99 SingleThread,
100 /// Split spatial rows across the current Rayon pool; requires the
101 /// `parallel` feature.
102 Parallel,
103}
104
105impl Default for Execution {
106 /// [`Execution::Parallel`] with the `parallel` feature, otherwise
107 /// [`Execution::SingleThread`].
108 fn default() -> Self {
109 if cfg!(feature = "parallel") {
110 Self::Parallel
111 } else {
112 Self::SingleThread
113 }
114 }
115}
116
117/// Prediction options.
118///
119/// ```
120/// use colorvideovdp::{Execution, Options, TemporalPadding};
121///
122/// let options = Options::default()
123/// .with_distortion_map(true)
124/// .with_temporal_padding(TemporalPadding::Symmetric)
125/// .with_execution(Execution::SingleThread);
126/// assert!(options.distortion_map);
127/// ```
128#[derive(Debug, Clone, PartialEq, Eq)]
129#[non_exhaustive]
130pub struct Options {
131 /// Return the raw per-pixel distortion map in addition to JOD.
132 pub distortion_map: bool,
133 /// Padding before the first frame of a sequence.
134 pub temporal_padding: TemporalPadding,
135 /// CPU execution policy.
136 pub execution: Execution,
137 /// Conservative upper bound on prediction buffer bytes, excluding caller-owned
138 /// inputs and evaluator calibration. Defaults to 1 GiB.
139 pub memory_limit_bytes: usize,
140}
141
142impl Default for Options {
143 fn default() -> Self {
144 Self {
145 distortion_map: false,
146 temporal_padding: TemporalPadding::default(),
147 execution: Execution::default(),
148 memory_limit_bytes: 1024 * 1024 * 1024,
149 }
150 }
151}
152
153impl Options {
154 /// Set the conservative prediction memory limit, in bytes.
155 #[must_use]
156 pub fn with_memory_limit_bytes(mut self, bytes: usize) -> Self {
157 self.memory_limit_bytes = bytes;
158 self
159 }
160
161 /// Set [`Options::distortion_map`].
162 #[must_use]
163 pub fn with_distortion_map(mut self, distortion_map: bool) -> Self {
164 self.distortion_map = distortion_map;
165 self
166 }
167
168 /// Set [`Options::temporal_padding`].
169 #[must_use]
170 pub fn with_temporal_padding(mut self, temporal_padding: TemporalPadding) -> Self {
171 self.temporal_padding = temporal_padding;
172 self
173 }
174
175 /// Set [`Options::execution`].
176 #[must_use]
177 pub fn with_execution(mut self, execution: Execution) -> Self {
178 self.execution = execution;
179 self
180 }
181}
182
183/// A raw distortion map in contiguous frame, row, column order.
184///
185/// Values are `1 - per_pixel_JOD / 10`, as in the reference `heatmap="raw"`
186/// output. They are not clipped to [0, 1] and are kept in f32; the reference
187/// quantizes its map to f16. Colour visualization is left to the caller.
188#[derive(Debug, Clone, PartialEq)]
189#[non_exhaustive]
190pub struct DistortionMap {
191 /// Width of each frame in pixels.
192 pub width: usize,
193 /// Height of each frame in pixels.
194 pub height: usize,
195 /// Number of map frames.
196 pub frames: usize,
197 /// One value per pixel per frame.
198 pub data: Vec<f32>,
199}
200
201/// A quality score, an optional raw distortion map, and pooled features.
202#[derive(Debug, Clone, PartialEq)]
203#[non_exhaustive]
204pub struct Prediction {
205 /// Quality in JOD units: 10 for no visible difference, lower is worse.
206 pub jod: f32,
207 /// Raw per-pixel map, when requested with [`Options::distortion_map`].
208 pub distortion_map: Option<DistortionMap>,
209 /// Number of visual channels: 3 for images, 4 for video (the extra one is
210 /// the achromatic transient channel).
211 pub channels: usize,
212 /// Number of input frames.
213 pub frames: usize,
214 /// Spatial band frequencies in cycles per degree; the last entry is the
215 /// 0.1 cpd baseband.
216 pub band_frequencies: Vec<f32>,
217 /// Spatially pooled differences in channel, frame, band order; the
218 /// reference's `Q_per_ch`.
219 pub quality_per_channel: Vec<f32>,
220}
221
222#[cfg(doctest)]
223#[doc = include_str!("../README.md")]
224struct ReadmeDoctests;