Ssimulacra2 (Ssimulacra2 v0.1.0)

SSIMULACRA2 perceptual image-quality metric for Elixir, backed by the fast-ssim2 Rust crate.

Inputs are packed binaries whose layout is chosen with the :format option (default :rgb888). The score is on the native SSIMULACRA2 0–100 scale: 100 is pixel-identical, ~90+ is visually lossless, and low/negative values indicate large perceptual differences.

Formats

format	element	channels	bytes/pixel	color space
`:rgb888` (default)	`u8`	3	3	sRGB (gamma)
`:rgb16`	`u16`	3	6	sRGB (gamma)
`:linear_rgb`	`f32`	3	12	linear RGB
`:gray8`	`u8`	1	1	sRGB grayscale
`:linear_gray`	`f32`	1	4	linear grayscale

Convention: integer elements are sRGB (gamma-encoded); float elements are linear RGB. Grayscale is expanded to RGB (R=G=B). Multi-byte elements (u16, f32) are native-endian — e.g. <<v::native-16>> / <<v::native-float-32>>. A binary's size must equal width * height * channels * bytes_per_element for its format.

Cancellation

compare/5 and Ssimulacra2.Reference.compare/3 accept cancel: (an Ssimulacra2.CancelRef) and timeout: (milliseconds) to abort a long comparison mid-computation, returning {:error, :cancelled} or {:error, :timeout}. Create a ref with Ssimulacra2.CancelRef.new/0 and trip it with cancel/1.

Summary

Types

image_data()

reason()

Functions

cancel(cancel_ref)

Trip an Ssimulacra2.CancelRef, aborting any comparison that uses it.

compare(reference, distorted, width, height, opts \\ [])

Compare a reference and distorted image of the same dimensions.

compare!(reference, distorted, width, height, opts \\ [])

Like compare/5 but returns the bare score and raises Ssimulacra2.Error on failure. Accepts the same format: option, defaulting to :rgb888.

Types

image_data()

@type image_data() :: binary()

reason()

@type reason() ::
  :invalid_dimensions
  | :size_mismatch
  | :dimension_mismatch
  | :unknown_format
  | :invalid_cancel
  | :invalid_timeout
  | :cancelled
  | :timeout
  | {:ssimulacra2, String.t()}

Functions

cancel(cancel_ref)

@spec cancel(Ssimulacra2.CancelRef.t()) :: :ok

Trip an Ssimulacra2.CancelRef, aborting any comparison that uses it.

Call from any process to cancel an in-flight compare/5 or Ssimulacra2.Reference.compare/3 that was passed this ref as cancel:. Returns :ok and is safe to call more than once.

compare(reference, distorted, width, height, opts \\ [])

@spec compare(image_data(), image_data(), pos_integer(), pos_integer(), keyword()) ::
  {:ok, float()} | {:error, reason()}

Compare a reference and distorted image of the same dimensions.

Pass format: to select the packed pixel layout; it defaults to :rgb888 (packed 8-bit sRGB, byte_size == width * height * 3). Other supported formats are :rgb16, :linear_rgb, :gray8, and :linear_gray.

Returns {:ok, score} or {:error, reason}.

Cancellation

Pass cancel: an Ssimulacra2.CancelRef to abort the comparison from another process (e.g. on client disconnect) — the call returns {:error, :cancelled}. Pass timeout: a positive integer of milliseconds to bound the wall-clock time — the call returns {:error, :timeout} if it exceeds that. Both may be combined; cancellation is checked at strip boundaries, so the CPU is freed promptly without leaving the dirty scheduler.

Invalid options return {:error, :invalid_cancel} / {:error, :invalid_timeout}.

compare!(reference, distorted, width, height, opts \\ [])

@spec compare!(image_data(), image_data(), pos_integer(), pos_integer(), keyword()) ::
  float()

Like compare/5 but returns the bare score and raises Ssimulacra2.Error on failure. Accepts the same format: option, defaulting to :rgb888.