Skip to main content

fidelity-kit

Metrics, delta images, suite processing and validation, plus everything exported by fidelity-kit/paths and fidelity-kit/scan.

Import from fidelity-kit.

Functions​

readRgb()​

function readRgb(input): Promise<RawImage>;

Decodes an image to 8-bit sRGB, dropping alpha.

Parameters​

ParameterTypeDescription
inputstring | Buffer<ArrayBufferLike>A file path or an encoded image buffer (AVIF, WebP, PNG or JPEG).

Returns​

Promise<RawImage>

The decoded pixels and dimensions.


gradientEnergy()​

function gradientEnergy(image): number;

Sum of absolute horizontal and vertical neighbour differences over all RGB channels.

Parameters​

ParameterTypeDescription
imageRawImageThe decoded image to measure.

Returns​

number

The total gradient energy; larger means more edges and detail.


sharpnessRatio()​

function sharpnessRatio(reference, test): number | null;

Gradient energy of test relative to reference; see ImageMetrics.sharpness.

Parameters​

ParameterTypeDescription
referenceRawImageThe reference image.
testRawImageThe image to judge against it.

Returns​

number | null

The ratio, or null when the reference has no gradient.


compareRgb()​

function compareRgb(reference, test): RgbComparison;

Computes metrics and an RGB heat-map delta image (black = identical) from two equal-size RGB images.

Parameters​

ParameterTypeDescription
referenceRawImageThe reference image.
testRawImageThe image to compare; it must have the same dimensions.

Returns​

RgbComparison

The metrics and the delta image, whose colour follows the largest channel error of each pixel.

Throws​

If the image dimensions differ.


measureImages()​

function measureImages(reference, test): Promise<ImageMeasurement>;

Computes metrics without encoding a heatmap, for when the cached heatmap is still current.

Parameters​

ParameterTypeDescription
referencestring | Buffer<ArrayBufferLike>The reference image as a path or encoded buffer.
teststring | Buffer<ArrayBufferLike>The image to compare as a path or encoded buffer.

Returns​

Promise<ImageMeasurement>

The metrics and the shared image dimensions.

Throws​

If the image dimensions differ.


compareImages()​

function compareImages(reference, test): Promise<ImageComparison>;

Compares two encoded images; returns metrics and a quality-85 WebP heatmap.

Parameters​

ParameterTypeDescription
referencestring | Buffer<ArrayBufferLike>The reference image as a path or encoded buffer.
teststring | Buffer<ArrayBufferLike>The image to compare as a path or encoded buffer.

Returns​

Promise<ImageComparison>

The metrics, the image dimensions and the encoded WebP delta image.

Throws​

If the image dimensions differ.

Example​

const { metrics, deltaImage } = await compareImages('reference.avif', 'my-renderer.avif');
console.log(metrics.psnr); // dB, or null when identical

resolveInside()​

function resolveInside(root, rel): string | null;

Resolves rel under root, refusing paths that escape it.

Parameters​

ParameterTypeDescription
rootstringThe directory to stay inside.
relstringA path relative to root.

Returns​

string | null

The absolute path, or null when it would leave root.


notModified()​

function notModified(
req,
etag,
mtimeMs
): boolean;

True when the request's validators say the client's copy is current (If-None-Match wins over If-Modified-Since).

Parameters​

ParameterTypeDescription
reqRequestThe incoming request.
etagstringThe file's current quoted ETag.
mtimeMsnumberThe file's modification time in milliseconds.

Returns​

boolean


fileResponse()​

function fileResponse(
req,
path,
opts?
): Promise<Response>;

Serves a file with CDN-friendly validators: strong ETag ("<size>-<crc32>", the content hash), Last-Modified, Content-Length, nosniff, and 304 on If-None-Match / If-Modified-Since. The body is streamed from disk. cacheControl defaults to no-cache (always revalidate); immutableIf is a ?v= version that becomes immutableCacheControl only if it equals the file's current hash (an unverified version keeps cacheControl). There is no Vary: the response never depends on request headers.

Parameters​

ParameterTypeDescription
reqRequestThe incoming request, used for conditional headers.
pathstringAbsolute path of the file to serve.
opts?{ cacheControl?: string; immutableIf?: string | null; store?: HashStore; }Caching options and an optional HashStore to reuse hashes across requests.
opts.cacheControl?string-
opts.immutableIf?string | null-
opts.store?HashStore-

Returns​

Promise<Response>

A 200 streaming response, a 304, or a 404 when the file does not exist.


freshFileResponse()​

function freshFileResponse(path): Promise<Response>;

Dev-mode variant: the file exactly as it is on disk right now, every time. No ETag, no Last-Modified, no hash cache, conditional headers are ignored (always 200) and Cache-Control: no-store keeps browsers and proxies from reusing it.

Parameters​

ParameterTypeDescription
pathstringAbsolute path of the file to serve.

Returns​

Promise<Response>

A 200 streaming response, or a 404 when the file does not exist.


hashFile()​

function hashFile(path): Promise<string>;

Content hash shared by the ETag and the ?v= URL version: <size>-<crc32> in base36. Streamed, so memory stays flat however large the file is. Fast and non-cryptographic: it detects change, it is not a security boundary.

Parameters​

ParameterTypeDescription
pathstringFile to hash.

Returns​

Promise<string>

The hash string <size>-<crc32>.


readHashFile()​

function readHashFile(root): Promise<Record<string, HashEntry>>;

The entries of <root>/image-hashes.json; empty when it is missing or malformed (they are only a cache).

Parameters​

ParameterTypeDescription
rootstringSuite root directory.

Returns​

Promise<Record<string, HashEntry>>

Hash entries keyed by path relative to the root.


hashSuite()​

function hashSuite(root, opts?): Promise<HashSuiteResult>;

Writes <root>/image-hashes.json for every served image. Incremental: an entry whose size and mtimeMs are unchanged is reused without reading the file. Output is sorted and timestamp-free, so unchanged files give identical bytes.

Parameters​

ParameterTypeDescription
rootstringSuite root directory.
opts?HashSuiteOptionsConcurrency, progress reporting and a hash function override.

Returns​

Promise<HashSuiteResult>


processSuite()​

function processSuite(root, opts?): Promise<ProcessResult>;

Scans a suite, computes the stale comparisons and writes metrics, delta images and index.json.

Parameters​

ParameterTypeDescription
rootstringSuite root containing fidelity.json.
opts?ProcessOptionsConcurrency, force and progress options.

Returns​

Promise<ProcessResult>

Counts of computed and skipped comparisons, failures and suite warnings.

Example​

const result = await processSuite('results', { concurrency: 2 });
console.log(`${result.computed} computed, ${result.skipped} up to date`);

processChanges()​

function processChanges(
root,
paths,
onProgress?
): Promise<ProcessResult>;

One-shot helper that reprocesses only the scenes affected by changed files, falling back to processSuite when there is no usable index. Watch mode retains its SuiteProcessor instead.

Parameters​

ParameterTypeDescription
rootstringSuite root containing fidelity.json.
pathsIterable<string>Changed file paths relative to the suite root.
onProgress?ProgressCallbackCalled as comparisons complete.

Returns​

Promise<ProcessResult>


parseConfig()​

function parseConfig(
data,
file?,
onWarning?
): FidelityConfig;

Validates a parsed fidelity.json against the published JSON Schema and checks that ids are unique and presets refer to declared renderers. Unknown properties are dropped with a warning.

Parameters​

ParameterTypeDefault valueDescription
dataunknownundefinedThe parsed JSON value.
file?string'fidelity.json'File name used in error and warning messages.
onWarning?(w) => voidundefinedReceives warnings for ignored properties.

Returns​

FidelityConfig

The validated configuration.

Throws​

SchemaValidationError listing every problem found.


parseSceneMeta()​

function parseSceneMeta(
data,
file?,
onWarning?
): SceneMeta;

Validates a parsed scene.json against the published JSON Schema.

Parameters​

ParameterTypeDefault valueDescription
dataunknownundefinedThe parsed JSON value.
file?string'scene.json'File name used in error and warning messages.
onWarning?(w) => voidundefinedReceives warnings for ignored properties.

Returns​

SceneMeta

The validated scene metadata.

Throws​

SchemaValidationError listing every problem found.


compareSequences()​

function compareSequences(reference, test): TemporalComparison;

Compares two equally long sequences of equally sized RGB frames.

Parameters​

ParameterTypeDescription
referenceRawImage[]Reference frames in playback order.
testRawImage[]Test frames in the same order and size.

Returns​

TemporalComparison

Per-frame and summary metrics, including frame-to-frame (temporal) PSNR.

Throws​

If the sequences differ in length or are empty.

Classes​

HashStore​

Lazy content-hash map keyed by absolute path: a file is hashed (streamed, CRC32) only when its mtime or size differs from the entry. Only the hash is kept, never the bytes, so memory stays flat however many images a suite has. Entries can be pre-populated from image-hashes.json; they are trusted only while the file's stat still matches.

Constructors​

Constructor​
new HashStore(): HashStore;
Returns​

HashStore

Methods​

preload()​
preload(path, entry): void;

Seeds the store with a known hash, for example one read from image-hashes.json.

Parameters​
ParameterType
pathstring
entryHashEntry
Returns​

void

entryFor()​
entryFor(
path,
mtimeMs,
size
): Promise<HashEntry>;

The hash entry for a file, hashing it only when the stored entry is missing or its mtime or size differs.

Parameters​
ParameterTypeDescription
pathstringAbsolute file path.
mtimeMsnumberThe file's current modification time in milliseconds.
sizenumberThe file's current size in bytes.
Returns​

Promise<HashEntry>

known()​
known(): Promise<Map<string, string>>;

Every hash that is valid right now: entries whose file changed or vanished are dropped.

Returns​

Promise<Map<string, string>>

Properties​

version​
version: number = 0;

Bumped whenever the set of known hashes changes; drives the ETag of the hash listing.


SuiteProcessor​

A fixed configuration, small per-scene dependency maps, and one bounded comparison queue.

Accessors​

needsFlush​
Get Signature​
get needsFlush(): boolean;

True while changes are pending, comparisons are running or the index needs writing.

Returns​

boolean

Methods​

create()​
static create(root, opts?): Promise<SuiteProcessor>;

Reads the suite configuration and prepares a processor without scanning or comparing anything yet.

Parameters​
ParameterTypeDescription
rootstringSuite root containing fidelity.json.
opts?ProcessOptionsConcurrency, force and progress options.
Returns​

Promise<SuiteProcessor>

Throws​

If fidelity.json is missing or invalid, or concurrency is not a positive integer.

sceneForInput()​
sceneForInput(path): string | null;

Maps a changed file to the scene it affects. Only source inputs qualify; generated deltas, metrics, the index and temporary files never do.

Parameters​
ParameterTypeDescription
pathstringFile path relative to the suite root, with / separators.
Returns​

string | null

The scene path, or null when the file is not a source input.

notify()​
notify(paths, defer?): void;

Invalidate synchronously, including work already running; reconciliation happens at the batch boundary.

Parameters​
ParameterTypeDefault valueDescription
pathsIterable<string>undefinedChanged file paths relative to the suite root.
defer?booleanfalseHold the scenes back until SuiteProcessor.settle is called.
Returns​

void

settle()​
settle(): void;

Release one coalesced watcher batch without delaying invalidation of running work.

Returns​

void

removeDirectory()​
removeDirectory(path, defer?): void;

Invalidates every scene inside, or containing, a removed directory.

Parameters​
ParameterTypeDefault valueDescription
pathstringundefinedDirectory path relative to the suite root.
defer?booleanfalseHold the scenes back until SuiteProcessor.settle is called.
Returns​

void

initialize()​
initialize(process?): Promise<ProcessResult>;

Scans the suite and runs stale comparisons. Comparisons start as scenes are discovered; no second walk or metrics reread is needed.

Parameters​
ParameterTypeDefault valueDescription
process?booleantruePass false to reuse the metrics in the existing index.json instead of computing any.
Returns​

Promise<ProcessResult>

flush()​
flush(): Promise<ProcessResult>;

Runs queued comparisons, rewrites the index when needed, and resolves with the accumulated result.

Returns​

Promise<ProcessResult>

Properties​

config​
readonly config: FidelityConfig;

The validated suite configuration.

root​
readonly root: string;

Suite root directory.


SchemaValidationError​

Thrown when fidelity.json or scene.json fails validation; every problem is listed in the message.

Extends​

  • Error

Constructors​

Constructor​
new SchemaValidationError(file, issues): SchemaValidationError;

Creates an error listing every validation problem.

Parameters​
ParameterTypeDescription
filestringName of the invalid file, used in the message.
issuesstring[]One description per problem found.
Returns​

SchemaValidationError

Overrides​

Error.constructor

Properties​

file​
readonly file: string;

Name of the invalid file.

issues​
readonly issues: string[];

One description per problem found.

Interfaces​

RawImage​

A decoded 8-bit RGB image.

Properties​

PropertyTypeDescription
dataBufferInterleaved R, G, B bytes, row by row, three bytes per pixel and no alpha.
widthnumberWidth in pixels.
heightnumberHeight in pixels.

ImageMetrics​

psnr is in dB over RGB 0–255, and null when the images are identical (infinite PSNR). sharpness is the gradient energy of the test image relative to the reference: 1 is equally sharp, below 1 is blurrier (for example temporal accumulation) and above 1 has extra edges (aliasing or noise). It is null when the reference is flat.

Extended by​

Properties​

PropertyTypeDescription
psnrnumber | nullPeak signal-to-noise ratio in dB, or null when the images are identical.
sharpness?number | nullGradient energy of the test image relative to the reference, or null when the reference is flat.

RgbComparison​

Result of compareRgb.

Properties​

PropertyTypeDescription
metricsImageMetricsQuality metrics of the test image.
deltaRawImageHeat-map of per-pixel error; black pixels are identical.

ImageMeasurement​

Result of measureImages.

Extended by​

Properties​

PropertyTypeDescription
metricsImageMetricsQuality metrics of the test image.
widthnumberWidth of the compared images in pixels.
heightnumberHeight of the compared images in pixels.

ImageComparison​

Result of compareImages.

Extends​

Properties​

PropertyTypeDescriptionInherited from
metricsImageMetricsQuality metrics of the test image.ImageMeasurement.metrics
widthnumberWidth of the compared images in pixels.ImageMeasurement.width
heightnumberHeight of the compared images in pixels.ImageMeasurement.height
deltaImageBufferThe delta heat-map encoded as WebP.-

HashEntry​

A cached content hash, valid while the file's size and modification time are unchanged.

Properties​

PropertyTypeDescription
hashstringContent hash as produced by hashFile.
sizenumberFile size in bytes when hashed.
mtimeMsnumberFile modification time in milliseconds when hashed.

HashSuiteOptions​

Options for hashSuite.

Properties​

PropertyTypeDescription
concurrency?numberParallel file reads; defaults to os.availableParallelism().
hash?(path) => Promise<string>Injectable for tests.
onProgress?ProgressCallbackCalled as files are hashed.

HashSuiteResult​

What hashSuite did.

Properties​

PropertyTypeDescription
hashednumberFiles that were read and hashed.
reusednumberFiles whose cached entry was still current.
totalnumberFiles in the hash file after the run.

MetricsRecord​

Metrics for one reference and renderer pair, as stored in the suite index.

Extends​

Properties​

PropertyTypeDescriptionInherited from
psnrnumber | nullPeak signal-to-noise ratio in dB, or null when the images are identical.ImageMetrics.psnr
sharpness?number | nullGradient energy of the test image relative to the reference, or null when the reference is flat.ImageMetrics.sharpness
widthnumberCompared image width in pixels.-
heightnumberCompared image height in pixels.-
generatedAtstringISO timestamp of when the comparison was computed.-
deltaFile?stringPresent in the viewer index; legacy entries refer to AVIF heatmaps.-

SuiteIndex​

The scanned Suite plus the metrics of every comparison; this is the index.json the viewer reads.

Extends​

Properties​

PropertyTypeDescriptionInherited from
metricsRecord<string, MetricsRecord>Metrics of every comparison, keyed by scene, output, reference and renderer.-
configFidelityConfigThe validated fidelity.json.Suite.config
hasReadmebooleanWhether the suite root contains a README.md preamble.Suite.hasReadme
rootGroupNodeThe root group, containing every scene.Suite.root

ProcessFailure​

A comparison that could not be computed.

Properties​

PropertyTypeDescription
filestringDelta file path of the failed comparison.
errorstringError message.

ProcessResult​

Outcome of processing a suite.

Properties​

PropertyTypeDescription
computednumberComparisons computed in this run.
skippednumberComparisons skipped because their cached results were current.
failedProcessFailure[]Comparisons that failed, with the delta file involved and the error message.
warningsSuiteWarning[]Suite files and folders that were ignored, from scans performed for this result.

ProcessOptions​

Options for processSuite and SuiteProcessor.create.

Properties​

PropertyTypeDescription
force?booleanRecompute every comparison, ignoring cached results.
concurrency?numberComparisons to run in parallel; a positive integer, defaulting to os.availableParallelism().
onCompute?(file) => voidCalled with the delta file path as each comparison starts.
onProgress?ProgressCallbackCalled as comparisons complete.

TemporalSummary​

Summary of a dynamic (temporal) comparison over the measured frames of a sequence.

Extended by​

Properties​

PropertyTypeDescription
psnrnumber | nullPSNR (dB) of the mean squared error over all measured frames; null when identical.
temporalPsnrnumber | nullPSNR (dB) of the frame-to-frame change, (test[t] − test[t−1]) − (reference[t] − reference[t−1]). It isolates flicker, shimmering and lag from a constant spatial error; null when the changes are identical.
sharpnessnumber | nullGradient energy of the test frames relative to the reference frames (1 = equally sharp, < 1 = blurrier).
framesnumberNumber of measured frames.

TemporalComparison​

Result of compareSequences.

Properties​

PropertyTypeDescription
summaryTemporalSummaryAggregate metrics over the whole sequence.
perFrameobjectMetrics for each measured frame, in order.
perFrame.psnr(number | null)[]PSNR (dB) of each frame against the reference; null for identical frames.
perFrame.temporalPsnr(number | null)[]null for the first measured frame, which has no predecessor.
perFrame.sharpness(number | null)[]Gradient energy of each test frame relative to the reference frame.

TemporalRecord​

<scene>/<output>/<renderer>.temporal.json: one compared renderer's sequence metrics.

Properties​

PropertyTypeDescription
schemaVersion1Format version of this record.
scenestringScene path relative to the suite root.
rendererstringId of the compared renderer.
referencestringId of the reference renderer it was compared against.
outputstringId of the output the sequence belongs to.
widthnumberFrame width in pixels.
heightnumberFrame height in pixels.
fpsnumberCapture frame rate.
warmupnumberFrames rendered before measurement began.
summaryTemporalSummaryAggregate metrics over the measured frames.
perFrameobjectMetrics for each measured frame, as in TemporalComparison.perFrame.
perFrame.psnr(number | null)[]PSNR (dB) of each frame against the reference; null for identical frames.
perFrame.temporalPsnr(number | null)[]null for the first measured frame, which has no predecessor.
perFrame.sharpness(number | null)[]Gradient energy of each test frame relative to the reference frame.
generatedAtstringISO timestamp of when the record was produced.

DynamicResult​

A renderer's temporal summary with the time it was produced.

Extends​

Properties​

PropertyTypeDescriptionInherited from
psnrnumber | nullPSNR (dB) of the mean squared error over all measured frames; null when identical.TemporalSummary.psnr
temporalPsnrnumber | nullPSNR (dB) of the frame-to-frame change, (test[t] − test[t−1]) − (reference[t] − reference[t−1]). It isolates flicker, shimmering and lag from a constant spatial error; null when the changes are identical.TemporalSummary.temporalPsnr
sharpnessnumber | nullGradient energy of the test frames relative to the reference frames (1 = equally sharp, < 1 = blurrier).TemporalSummary.sharpness
framesnumberNumber of measured frames.TemporalSummary.frames
generatedAtstringISO timestamp of when the result was produced.-

DynamicIndex​

<root>/dynamic.json: summaries of every dynamic comparison, keyed by scene path then renderer.

Properties​

PropertyTypeDescription
schemaVersion1Format version of this index.
outputstringId of the output the results belong to.
referencestringId of the reference renderer the results compare against.
resultsRecord<string, Record<string, DynamicResult>>Summaries keyed by scene path, then renderer id.

References​

IMAGE_EXT​

Re-exports IMAGE_EXT


IMAGE_EXTENSIONS​

Re-exports IMAGE_EXTENSIONS


imageFile​

Re-exports imageFile


isImageFile​

Re-exports isImageFile


metricsFile​

Re-exports metricsFile


temporalFile​

Re-exports temporalFile


DYNAMIC_INDEX​

Re-exports DYNAMIC_INDEX


deltaFile​

Re-exports deltaFile


isDataFile​

Re-exports isDataFile


isLogoFile​

Re-exports isLogoFile


logoUrl​

Re-exports logoUrl


SceneNode​

Re-exports SceneNode


GroupNode​

Re-exports GroupNode


Suite​

Re-exports Suite


ScanWarningCallback​

Re-exports ScanWarningCallback


readConfig​

Re-exports readConfig


scanSuite​

Re-exports scanSuite


scanScene​

Re-exports scanScene


allScenes​

Re-exports allScenes

Type Aliases​

FidelityConfig​

type FidelityConfig = object;

<root>/fidelity.json. Renderer/output ids and labels are entirely up to the suite.

Properties​

title​
title: string;

Heading shown at the top of the viewer.

staticFidelity?​
staticFidelity?: boolean;

Disable static comparisons for temporal-only or performance-only result trees.

logo?: string;

Path to a branding image, relative to the suite root.

renderers​
renderers: object[];

The renderers to compare; at least one should be marked as a reference.

id​
id: string;

Lowercase letters, numbers, ., _ or -; used in image file names.

label?​
label?: string;

Display name; defaults to the id.

reference?​
reference?: boolean;

Marks a renderer others are compared against.

enabled?​
enabled?: boolean;

false hides the renderer by default; viewers can still toggle it on.

category?​
category?: string;

Optional grouping label for the viewer.

comparisonPresets?​
comparisonPresets?: object[];

Named renderer selections the viewer offers, optionally pinned to a reference.

id​
id: string;

Unique preset id.

name​
name: string;

Display name.

renderers​
renderers: string[];

Ids of the renderers the preset shows.

ref?​
ref?: string;

Id of the reference renderer to compare against; it must be marked reference.

outputs​
outputs: object[];

The outputs rendered for each scene, such as beauty or ao.

id​
id: string;

Output folder name; unique within the suite.

label?​
label?: string;

Display name; defaults to the id.

kind?​
kind?: "static" | "temporal";

temporal marks representative frames of animated sequences, which are not scored as static captures.


SceneMeta​

type SceneMeta = object;

Optional <scene>/scene.json.

Properties​

title?​
title?: string;

Display title; defaults to the folder name.

category?​
category?: string;

Grouping label for scene filters.

tags​
tags: string[];

Search tags.


SuiteWarning​

type SuiteWarning = object;

Something in the suite that fidelity-kit ignores; path is relative to the suite root.

Properties​

path​
path: string;

Path of the ignored content, relative to the suite root.

message​
message: string;

Why it is ignored.

Variables​

RESULT_AVIF​

const RESULT_AVIF: object;

Sharp AVIF options for committed result images: near-lossless (worst render ~40 dB PSNR vs PNG), full-res chroma so noise and false colour survive.

Type Declaration​

NameTypeDefault valueDescription
quality9090AVIF quality, 0 to 100.
chromaSubsampling"4:4:4"'4:4:4'Chroma subsampling mode; 4:4:4 keeps full-resolution colour.

DELTA_WEBP​

const DELTA_WEBP: object;

Sharp WebP options for delta heatmaps. They trade minor visual differences for smaller files at modest encoding cost.

Type Declaration​

NameTypeDefault valueDescription
quality8585WebP quality, 0 to 100.
effort44Encoder effort, 0 (fastest) to 6 (smallest).

IMMUTABLE​

const IMMUTABLE: "public, max-age=31536000, immutable" = 'public, max-age=31536000, immutable';

Cache-Control value for content-addressed files that never change.


HASHES_FILE​

const HASHES_FILE: "image-hashes.json" = 'image-hashes.json';

Name of the hash cache file written at the suite root.


schemaFiles​

const schemaFiles: object;

The published JSON Schemas in schemas/ are the source of truth; these types mirror them. Suites can reference the same files from $schema for editor validation, or validate in their own tooling.

Type Declaration​

NameTypeDescription
configURLfidelity.schema.json, describing fidelity.json.
sceneURLscene.schema.json, describing scene.json.