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
| Parameter | Type | Description |
|---|---|---|
input | string | 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
| Parameter | Type | Description |
|---|---|---|
image | RawImage | The 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
| Parameter | Type | Description |
|---|---|---|
reference | RawImage | The reference image. |
test | RawImage | The 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
| Parameter | Type | Description |
|---|---|---|
reference | RawImage | The reference image. |
test | RawImage | The image to compare; it must have the same dimensions. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
reference | string | Buffer<ArrayBufferLike> | The reference image as a path or encoded buffer. |
test | string | 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
| Parameter | Type | Description |
|---|---|---|
reference | string | Buffer<ArrayBufferLike> | The reference image as a path or encoded buffer. |
test | string | 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
| Parameter | Type | Description |
|---|---|---|
root | string | The directory to stay inside. |
rel | string | A 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
| Parameter | Type | Description |
|---|---|---|
req | Request | The incoming request. |
etag | string | The file's current quoted ETag. |
mtimeMs | number | The 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
| Parameter | Type | Description |
|---|---|---|
req | Request | The incoming request, used for conditional headers. |
path | string | Absolute 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
| Parameter | Type | Description |
|---|---|---|
path | string | Absolute 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
| Parameter | Type | Description |
|---|---|---|
path | string | File 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
| Parameter | Type | Description |
|---|---|---|
root | string | Suite 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
| Parameter | Type | Description |
|---|---|---|
root | string | Suite root directory. |
opts? | HashSuiteOptions | Concurrency, 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
| Parameter | Type | Description |
|---|---|---|
root | string | Suite root containing fidelity.json. |
opts? | ProcessOptions | Concurrency, 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
| Parameter | Type | Description |
|---|---|---|
root | string | Suite root containing fidelity.json. |
paths | Iterable<string> | Changed file paths relative to the suite root. |
onProgress? | ProgressCallback | Called 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
| Parameter | Type | Default value | Description |
|---|---|---|---|
data | unknown | undefined | The parsed JSON value. |
file? | string | 'fidelity.json' | File name used in error and warning messages. |
onWarning? | (w) => void | undefined | Receives warnings for ignored properties. |
Returns
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
| Parameter | Type | Default value | Description |
|---|---|---|---|
data | unknown | undefined | The parsed JSON value. |
file? | string | 'scene.json' | File name used in error and warning messages. |
onWarning? | (w) => void | undefined | Receives warnings for ignored properties. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
reference | RawImage[] | Reference frames in playback order. |
test | RawImage[] | Test frames in the same order and size. |
Returns
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
Methods
preload()
preload(path, entry): void;
Seeds the store with a known hash, for example one read from image-hashes.json.
Parameters
| Parameter | Type |
|---|---|
path | string |
entry | HashEntry |
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
| Parameter | Type | Description |
|---|---|---|
path | string | Absolute file path. |
mtimeMs | number | The file's current modification time in milliseconds. |
size | number | The 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
| Parameter | Type | Description |
|---|---|---|
root | string | Suite root containing fidelity.json. |
opts? | ProcessOptions | Concurrency, 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
| Parameter | Type | Description |
|---|---|---|
path | string | File 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
| Parameter | Type | Default value | Description |
|---|---|---|---|
paths | Iterable<string> | undefined | Changed file paths relative to the suite root. |
defer? | boolean | false | Hold 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
| Parameter | Type | Default value | Description |
|---|---|---|---|
path | string | undefined | Directory path relative to the suite root. |
defer? | boolean | false | Hold 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
| Parameter | Type | Default value | Description |
|---|---|---|---|
process? | boolean | true | Pass 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
| Parameter | Type | Description |
|---|---|---|
file | string | Name of the invalid file, used in the message. |
issues | string[] | One description per problem found. |
Returns
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
| Property | Type | Description |
|---|---|---|
data | Buffer | Interleaved R, G, B bytes, row by row, three bytes per pixel and no alpha. |
width | number | Width in pixels. |
height | number | Height 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
RgbComparison
Result of compareRgb.
Properties
| Property | Type | Description |
|---|---|---|
metrics | ImageMetrics | Quality metrics of the test image. |
delta | RawImage | Heat-map of per-pixel error; black pixels are identical. |
ImageMeasurement
Result of measureImages.
Extended by
Properties
| Property | Type | Description |
|---|---|---|
metrics | ImageMetrics | Quality metrics of the test image. |
width | number | Width of the compared images in pixels. |
height | number | Height of the compared images in pixels. |
ImageComparison
Result of compareImages.
Extends
Properties
| Property | Type | Description | Inherited from |
|---|---|---|---|
metrics | ImageMetrics | Quality metrics of the test image. | ImageMeasurement.metrics |
width | number | Width of the compared images in pixels. | ImageMeasurement.width |
height | number | Height of the compared images in pixels. | ImageMeasurement.height |
deltaImage | Buffer | The delta heat-map encoded as WebP. | - |
HashEntry
A cached content hash, valid while the file's size and modification time are unchanged.
Properties
| Property | Type | Description |
|---|---|---|
hash | string | Content hash as produced by hashFile. |
size | number | File size in bytes when hashed. |
mtimeMs | number | File modification time in milliseconds when hashed. |
HashSuiteOptions
Options for hashSuite.
Properties
HashSuiteResult
What hashSuite did.
Properties
| Property | Type | Description |
|---|---|---|
hashed | number | Files that were read and hashed. |
reused | number | Files whose cached entry was still current. |
total | number | Files in the hash file after the run. |
MetricsRecord
Metrics for one reference and renderer pair, as stored in the suite index.
Extends
Properties
| Property | Type | Description | Inherited from |
|---|---|---|---|
psnr | number | null | Peak signal-to-noise ratio in dB, or null when the images are identical. | ImageMetrics.psnr |
sharpness? | number | null | Gradient energy of the test image relative to the reference, or null when the reference is flat. | ImageMetrics.sharpness |
width | number | Compared image width in pixels. | - |
height | number | Compared image height in pixels. | - |
generatedAt | string | ISO timestamp of when the comparison was computed. | - |
deltaFile? | string | Present 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
| Property | Type | Description | Inherited from |
|---|---|---|---|
metrics | Record<string, MetricsRecord> | Metrics of every comparison, keyed by scene, output, reference and renderer. | - |
config | FidelityConfig | The validated fidelity.json. | Suite.config |
hasReadme | boolean | Whether the suite root contains a README.md preamble. | Suite.hasReadme |
root | GroupNode | The root group, containing every scene. | Suite.root |
ProcessFailure
A comparison that could not be computed.
Properties
| Property | Type | Description |
|---|---|---|
file | string | Delta file path of the failed comparison. |
error | string | Error message. |
ProcessResult
Outcome of processing a suite.
Properties
| Property | Type | Description |
|---|---|---|
computed | number | Comparisons computed in this run. |
skipped | number | Comparisons skipped because their cached results were current. |
failed | ProcessFailure[] | Comparisons that failed, with the delta file involved and the error message. |
warnings | SuiteWarning[] | Suite files and folders that were ignored, from scans performed for this result. |
ProcessOptions
Options for processSuite and SuiteProcessor.create.
Properties
TemporalSummary
Summary of a dynamic (temporal) comparison over the measured frames of a sequence.
Extended by
Properties
TemporalComparison
Result of compareSequences.
Properties
| Property | Type | Description |
|---|---|---|
summary | TemporalSummary | Aggregate metrics over the whole sequence. |
perFrame | object | Metrics 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
| Property | Type | Description |
|---|---|---|
schemaVersion | 1 | Format version of this record. |
scene | string | Scene path relative to the suite root. |
renderer | string | Id of the compared renderer. |
reference | string | Id of the reference renderer it was compared against. |
output | string | Id of the output the sequence belongs to. |
width | number | Frame width in pixels. |
height | number | Frame height in pixels. |
fps | number | Capture frame rate. |
warmup | number | Frames rendered before measurement began. |
summary | TemporalSummary | Aggregate metrics over the measured frames. |
perFrame | object | Metrics 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. |
generatedAt | string | ISO timestamp of when the record was produced. |
DynamicResult
A renderer's temporal summary with the time it was produced.
Extends
Properties
| Property | Type | Description | Inherited from |
|---|---|---|---|
psnr | number | null | PSNR (dB) of the mean squared error over all measured frames; null when identical. | TemporalSummary.psnr |
temporalPsnr | number | null | PSNR (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 |
sharpness | number | null | Gradient energy of the test frames relative to the reference frames (1 = equally sharp, < 1 = blurrier). | TemporalSummary.sharpness |
frames | number | Number of measured frames. | TemporalSummary.frames |
generatedAt | string | ISO timestamp of when the result was produced. | - |
DynamicIndex
<root>/dynamic.json: summaries of every dynamic comparison, keyed by scene path then renderer.
Properties
| Property | Type | Description |
|---|---|---|
schemaVersion | 1 | Format version of this index. |
output | string | Id of the output the results belong to. |
reference | string | Id of the reference renderer the results compare against. |
results | Record<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?
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
| Name | Type | Default value | Description |
|---|---|---|---|
quality | 90 | 90 | AVIF 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
| Name | Type | Default value | Description |
|---|---|---|---|
quality | 85 | 85 | WebP quality, 0 to 100. |
effort | 4 | 4 | Encoder 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
| Name | Type | Description |
|---|---|---|
config | URL | fidelity.schema.json, describing fidelity.json. |
scene | URL | scene.schema.json, describing scene.json. |