Skip to main content

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;