Skip to main content

fidelity-kit/scan

Scans a results folder into a tree of groups and scenes.

Import from fidelity-kit/scan.

Functions​

readConfig()​

function readConfig(root, onWarning?): Promise<FidelityConfig>;

Reads and validates <root>/fidelity.json.

Parameters​

ParameterTypeDescription
rootstringSuite root directory.
onWarning?ScanWarningCallbackReceives warnings for ignored properties.

Returns​

Promise<FidelityConfig>

The validated configuration.

Throws​

If the file is missing, is not valid JSON, or fails validation.


scanSuite()​

function scanSuite(root, options?): Promise<Suite>;

Walks a results folder and returns its groups and scenes. A directory is a scene when it contains a configured source image or scene.json.

Parameters​

ParameterTypeDescription
rootstringSuite root directory.
options?{ config?: FidelityConfig; onScene?: (scene) => Promise<void>; onProgress?: ProgressCallback; onWarning?: ScanWarningCallback; }A preloaded config, an onScene hook, progress reporting and a warning callback.
options.config?FidelityConfig-
options.onScene?(scene) => Promise<void>-
options.onProgress?ProgressCallback-
options.onWarning?ScanWarningCallbackFiles and folders that look like suite content but are ignored.

Returns​

Promise<Suite>

The suite tree.

Throws​

If root is not a directory or fidelity.json is missing or invalid.

Example​

const suite = await scanSuite('results');
for (const scene of allScenes(suite.root)) console.log(scene.path, scene.images);

scanScene()​

function scanScene(
root,
rel,
config,
onWarning?
): Promise<SceneNode | null>;

Scan one known scene without walking the rest of the suite.

Parameters​

ParameterTypeDescription
rootstringSuite root directory.
relstringScene path relative to the root.
configFidelityConfigThe suite configuration.
onWarning?ScanWarningCallbackReceives warnings about ignored content.

Returns​

Promise<SceneNode | null>

The scene, or null when the folder is missing or is not a scene.


allScenes()​

function allScenes(g): Generator<SceneNode>;

Iterates every scene in a group and its descendants, depth first.

Parameters​

ParameterTypeDescription
gGroupNodeThe group to walk, usually suite.root.

Returns​

Generator<SceneNode>

Interfaces​

SceneNode​

A scene found in a suite: a folder holding renderer images or a scene.json.

Properties​

PropertyTypeDescription
pathstringSlash-joined path from the root, e.g. surfaces/standard_surface/brass.
titlestringDisplay title from scene.json, defaulting to the folder name.
category?stringOptional category from scene.json.
tagsstring[]Search tags from scene.json.
hasReadmebooleanWhether the scene folder contains a README.md.
imagesRecord<string, string[]>output id -> renderer ids that have an image
imageFiles?Record<string, Record<string, string>>Selected source filenames by output and renderer; absent in legacy indexes.

GroupNode​

A folder that groups scenes and other groups. The suite root is the group with an empty path.

Properties​

PropertyTypeDescription
pathstringSlash-joined path from the suite root; empty for the root.
hasReadmebooleanWhether the group folder contains a README.md.
groupsGroupNode[]Nested groups.
scenesSceneNode[]Scenes directly inside this group.

Suite​

A scanned results folder.

Extended by​

Properties​

PropertyTypeDescription
configFidelityConfigThe validated fidelity.json.
hasReadmebooleanWhether the suite root contains a README.md preamble.
rootGroupNodeThe root group, containing every scene.

Type Aliases​

ScanWarningCallback​

type ScanWarningCallback = (warning) => void;

Receives something in the suite that fidelity-kit ignores.

Parameters​

ParameterType
warningSuiteWarning

Returns​

void