@spec compare(Vix.Vips.Image.t(), Vix.Vips.Image.t(), keyword()) ::
  {:ok, Butteraugli.Result.t()} | {:error, term()}

@spec compare(Butteraugli.Reference.t(), Vix.Vips.Image.t(), keyword()) ::
  {:ok, Butteraugli.Result.t()} | {:error, term()}

Compare a Vix candidate against a reference.

With two images, the reference is rebuilt every call. With a precomputed Butteraugli.Reference as the first argument, it is reused against the candidate (the reference's baked-in tuning parameters apply). Pass the same options as Butteraugli.compare/5 (:compute_diffmap, :intensity_target, :hf_asymmetry, :cancel, :timeout); :format is always :rgb888 here. For the precompute form only :cancel/:timeout apply.

@spec reference(
  Vix.Vips.Image.t(),
  keyword()
) :: {:ok, Butteraugli.Reference.t()} | {:error, term()}

Build a Butteraugli.Reference from a Vix image (coerced to :rgb888).

Accepts the same tuning options as Butteraugli.Reference.new/4 (:intensity_target, :hf_asymmetry, :compute_diffmap).