interpolation

module src.interpolation

Interpolation utilities for quality-metric target matching.

This module provides functions to estimate encoder quality settings that produce a desired output metric value (e.g., SSIMULACRA2 = 70 or bits_per_pixel = 0.3) using linear interpolation between measured data points from the pipeline.

The typical workflow is:

1. Load pipeline measurements from quality.json. 2. For each image × format combination, gather sorted (encoder_quality, measured_metric) pairs. 3. Linearly interpolate the encoder quality required to hit a target metric value.

All interpolation is linear between the two nearest bracketing measured points. If the target falls outside the measured range, None is returned.

---

function interpolate_quality_for_metric

interpolate_quality_for_metric(
    measurements: 'list[dict[str, Any]]',
    fmt: 'str',
    metric: 'str',
    target_value: 'float',
    source_image: 'str | None' = None,
    speed: 'int | None' = None,
    effort: 'int | None' = None,
    method: 'int | None' = None,
    chroma_subsampling: 'str | None' = None,
    resolution: 'int | None' = None,
    crop: 'int | None' = None
) → float | None

Find the encoder quality setting that produces target_value of metric.

Filters measurements by format (and optionally by source image and other encoder parameters), builds sorted (quality, metric_value) pairs, and linearly interpolates.

For bits_per_pixel the metric value is computed from 8 * file_size / (width * height).

Args:

• measurements: List of measurement dicts (from quality.json).
• fmt: Encoder format to filter on.
• metric: Target metric name.
• target_value: Desired metric value.
• source_image: If given, restrict to this source image path.
• speed: Filter on AVIF speed.
• effort: Filter on JXL effort.
• method: Filter on WebP method.
• chroma_subsampling: Filter on chroma subsampling.
• resolution: Filter on resolution.
• crop: Filter on crop level.

Returns: Interpolated encoder quality as a float, or None if the target falls outside the measured range.

---

function interpolate_metric_at_quality

interpolate_metric_at_quality(
    measurements: 'list[dict[str, Any]]',
    fmt: 'str',
    quality: 'float',
    output_metric: 'str',
    source_image: 'str | None' = None,
    speed: 'int | None' = None,
    effort: 'int | None' = None,
    method: 'int | None' = None,
    chroma_subsampling: 'str | None' = None,
    resolution: 'int | None' = None,
    crop: 'int | None' = None
) → float | None

Interpolate an output metric at a given encoder quality.

Uses cubic-spline interpolation when at least _SPLINE_MIN_POINTS measured quality levels are available. Falls back to piecewise-linear interpolation for sparser data so that measurements with only a handful of quality levels still produce valid results.

Args:

• measurements: List of measurement dicts.
• fmt: Encoder format to filter on.
• quality: The encoder quality setting (may be fractional).
• output_metric: Metric to interpolate.
• source_image: If given, restrict to this source image path.
• speed: Filter on AVIF speed.
• effort: Filter on JXL effort.
• method: Filter on WebP method.
• chroma_subsampling: Filter on chroma subsampling.
• resolution: Filter on resolution.
• crop: Filter on crop level.

Returns: Interpolated metric value, or None if out of range.

---

function compute_cross_format_cv

compute_cross_format_cv(
    measurements: 'list[dict[str, Any]]',
    source_image: 'str',
    tile_param: 'str',
    target_metric: 'str',
    target_value: 'float',
    output_metric: 'str'
) → float | None

Compute the coefficient of variation (CV) of output_metric across tile-parameter values.

For a given source image, for each unique value of tile_param (e.g., each format), interpolates the encoder quality that achieves target_value of target_metric, then interpolates what output_metric would be at that quality. Returns std / mean (relative standard deviation) of output_metric across tile-parameter values.

Using CV instead of raw variance prevents bias towards images or fragments with inherently high absolute metric values: a low-quality image has the same chance of being selected as a high-quality one if its relative spread across tile-parameter values is equally large.

Args:

• measurements: All measurements.
• source_image: Source image path.
• tile_param: Parameter that varies within comparison tiles (e.g. “format”).
• target_metric: Metric being targeted (e.g. “ssimulacra2”).
• target_value: Target value of target_metric.
• output_metric: Metric whose CV we compute (e.g. “bits_per_pixel”).

Returns: CV (std / mean) of output_metric across tile-param values, or None if fewer than 2 tile-param values have valid interpolations or if the mean is zero.

---

function select_best_image

select_best_image(
    measurements: 'list[dict[str, Any]]',
    tile_param: 'str',
    target_metric: 'str',
    target_values: 'list[float]',
    output_metric: 'str',
    exclude_images: 'list[str] | None' = None
) → str | None

Select the source image with highest mean anisotropic relative standard deviation.

For each source image and each target value, computes the cross-format coefficient of variation (CV = std / mean) of output_metric. The image with the highest mean CV across all target values is returned.

Using CV instead of raw variance avoids privileging high-metric images: a darker / lower-quality image is equally likely to be selected if its relative spread across formats is as large.

Args:

• measurements: All measurements from quality.json.
• tile_param: Parameter that varies within comparison tiles.
• target_metric: Metric being targeted.
• target_values: List of target values.
• output_metric: Metric whose CV we maximise.
• exclude_images: Optional list of image filenames to skip. Matched against the basename of each image path.

Returns: Path string of the selected source image, or None if no valid image could be found.