@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/starter/scripts/toolcraft-motion-reference-group-inventory.mjs

@@ -0,0 +1,148 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  defineToolcraftMotionReferenceEvidence,
+  writeCanonicalToolcraftMotionReferenceEvidence,
+} from "../src/app/acceptance/motion-reference-evidence.mjs";
+import {
+  createToolcraftMotionReferenceGroupId,
+  createToolcraftMotionReferenceId,
+  createToolcraftMotionReferenceStudyId,
+  createToolcraftSha256,
+  getToolcraftMotionReferenceEvidenceGroupErrors,
+} from "./toolcraft-motion-reference-artifacts.mjs";
+import {
+  requireToolcraftMotionReferenceStudiesRoot,
+} from "./toolcraft-motion-reference-roots.mjs";
+
+function fail(message, cause) {
+  throw new Error(`Toolcraft motion reference group inventory failed: ${message}`, {
+    cause,
+  });
+}
+
+function publicationScope(evidence) {
+  if (evidence.reviewPartition) return evidence.reviewPartition.scope;
+  if (evidence.timingMode === "seconds") return evidence.segment ?? {
+    endSeconds: evidence.durationSeconds,
+    startSeconds: 0,
+  };
+  return {
+    endFrameExclusive: evidence.decodedFrameCount,
+    startFrameIndex: 0,
+  };
+}
+
+function publicationGroupId(evidence) {
+  const expected = createToolcraftMotionReferenceGroupId(
+    evidence, publicationScope(evidence),
+  );
+  if (evidence.reviewPartition && evidence.reviewPartition.groupId !== expected) {
+    fail("partition group identity does not match its canonical source scope");
+  }
+  return expected;
+}
+
+export function defineToolcraftMotionReferencePublicationGroup(evidences) {
+  if (!Array.isArray(evidences) || evidences.length === 0) {
+    fail("a nonempty new evidence group is required");
+  }
+  const errors = getToolcraftMotionReferenceEvidenceGroupErrors(evidences);
+  if (errors.length > 0) fail(errors.join("\n"));
+  const referenceIds = new Set(evidences.map(createToolcraftMotionReferenceId));
+  const groupIds = new Set(evidences.map(publicationGroupId));
+  if (referenceIds.size !== 1 || groupIds.size !== 1) {
+    fail("new evidence must form exactly one complete canonical source group");
+  }
+  return {
+    groupId: groupIds.values().next().value,
+    referenceId: referenceIds.values().next().value,
+    studyIds: evidences.map(({ studyId }) => studyId).sort(),
+  };
+}
+
+async function checkedRegularFile(fileSystem, filePath, label) {
+  const file = await fileSystem.lstat(filePath).catch((error) => {
+    fail(`${label} is missing or unreadable`, error);
+  });
+  if (!file.isFile() || file.isSymbolicLink()) {
+    fail(`${label} must be a direct regular file, not a link`);
+  }
+  return fileSystem.readFile(filePath);
+}
+
+async function readStudy(fileSystem, referenceStudiesRoot, entry) {
+  if (!entry.isDirectory() || entry.isSymbolicLink()) {
+    fail(`unexplained reference study entry: ${entry.name}`);
+  }
+  const directory = path.join(referenceStudiesRoot, entry.name);
+  const names = (await fileSystem.readdir(directory)).sort();
+  if (names.join("\0") !== "contact-sheet.png\0evidence.json") {
+    fail(`reference study ${entry.name} must contain exactly its evidence and contact sheet`);
+  }
+  const evidenceBytes = await checkedRegularFile(
+    fileSystem, path.join(directory, "evidence.json"), `${entry.name}/evidence.json`,
+  );
+  let raw;
+  try {
+    raw = JSON.parse(evidenceBytes.toString("utf8"));
+  } catch (error) {
+    fail(`${entry.name}/evidence.json must contain strict JSON`, error);
+  }
+  let evidence;
+  try {
+    evidence = defineToolcraftMotionReferenceEvidence(raw);
+  } catch (error) {
+    fail(`${entry.name}/evidence.json is not canonical evidence`, error);
+  }
+  if (evidenceBytes.toString("utf8") !==
+      writeCanonicalToolcraftMotionReferenceEvidence(evidence) ||
+      evidence.studyId !== entry.name ||
+      createToolcraftMotionReferenceStudyId(evidence) !== entry.name) {
+    fail(`reference study ${entry.name} does not match its canonical identity`);
+  }
+  const sheet = await checkedRegularFile(fileSystem,
+    path.join(directory, "contact-sheet.png"), `${entry.name}/contact-sheet.png`);
+  if (createToolcraftSha256(sheet) !== evidence.contactSheet.sha256) {
+    fail(`reference study ${entry.name} contact-sheet hash is invalid`);
+  }
+  return {
+    evidence,
+    groupId: publicationGroupId(evidence),
+    referenceId: createToolcraftMotionReferenceId(evidence),
+    studyId: evidence.studyId,
+  };
+}
+
+export async function discoverToolcraftMotionReferencePreviousGroup({
+  evidences,
+  fileSystem = fs,
+  referenceStudiesRoot,
+  rootDir,
+}) {
+  await requireToolcraftMotionReferenceStudiesRoot({
+    fileSystem, referenceStudiesRoot, rootDir,
+  });
+  const authority = defineToolcraftMotionReferencePublicationGroup(evidences);
+  const entries = await fileSystem.readdir(referenceStudiesRoot, { withFileTypes: true });
+  const records = [];
+  for (const entry of [...entries].sort((left, right) =>
+    left.name.localeCompare(right.name))) {
+    records.push(await readStudy(fileSystem, referenceStudiesRoot, entry));
+  }
+  const previous = records.filter((record) =>
+    record.referenceId === authority.referenceId &&
+    record.groupId === authority.groupId);
+  if (previous.length > 0) {
+    const errors = getToolcraftMotionReferenceEvidenceGroupErrors(
+      previous.map(({ evidence }) => evidence),
+    );
+    if (errors.length > 0) fail(errors.join("\n"));
+  }
+  return {
+    obsoleteStudyIds: previous
+      .filter(({ studyId }) => !authority.studyIds.includes(studyId))
+      .map(({ studyId }) => studyId),
+  };
+}

package/templates/starter/scripts/toolcraft-motion-reference-image-filter-graph.mjs

@@ -0,0 +1,101 @@
+import {
+  createToolcraftMotionAnalysisGraph,
+  createToolcraftMotionAnalysisOutputArguments,
+} from "./toolcraft-motion-reference-analysis-protocol.mjs";
+
+function fail(message) {
+  throw new TypeError(`Invalid Toolcraft image filter graph input: ${message}`);
+}
+
+function validateIndices(inspection, indices) {
+  if (!inspection || !Array.isArray(inspection.frames) ||
+      !Array.isArray(indices) || indices.length === 0 ||
+      indices.some((index) => !Number.isInteger(index) || index < 0 ||
+        index >= inspection.frames.length)) {
+    fail("source frame indices must identify inspected frames");
+  }
+}
+
+function sequenceGraph(inspection, indices) {
+  if (inspection.sourceKind === "frame-sequence") {
+    const args = indices.flatMap((index) => ["-i", inspection.frames[index].sourceLocator]);
+    if (indices.length === 1) return { args, graph: "[0:v]null[sequence]" };
+    const labels = indices.map((_, inputIndex) => `[${inputIndex}:v]`).join("");
+    return { args, graph: `${labels}concat=n=${indices.length}:v=1:a=0[sequence]` };
+  }
+  if (inspection.sourceKind !== "contact-sheet") fail("source kind is unsupported");
+  if (typeof inspection.inputPath !== "string" || inspection.inputPath.length === 0) {
+    fail("contact-sheet input path is required");
+  }
+  const args = ["-i", inspection.inputPath];
+  const crops = indices.map((index, inputIndex) => {
+    const { column, row } = inspection.frames[index].cell;
+    return `[0:v]crop=w=${inspection.width}:h=${inspection.height}:` +
+      `x=${column * inspection.width}:y=${row * inspection.height}[cell${inputIndex}]`;
+  });
+  if (indices.length === 1) {
+    return { args, graph: `${crops[0]};[cell0]null[sequence]` };
+  }
+  const labels = indices.map((_, inputIndex) => `[cell${inputIndex}]`).join("");
+  return {
+    args,
+    graph: `${crops.join(";")};${labels}concat=n=${indices.length}:v=1:a=0[sequence]`,
+  };
+}
+
+function timestampExpression(frameTimes) {
+  if (frameTimes.length === 1) return `${frameTimes[0]}/TB`;
+  let expression = `${frameTimes.at(-1)}/TB`;
+  for (let index = frameTimes.length - 2; index >= 0; index -= 1) {
+    expression = `if(eq(N,${index}),${frameTimes[index]}/TB,${expression})`;
+  }
+  return `'${expression}'`;
+}
+
+function analysisTimeline(inspection, indices, timelineMode) {
+  if (timelineMode === "loop-seam" || inspection.timingMode === "ordinal") {
+    return "[sequence]settb=AVTB,setpts=N/TB[timed]";
+  }
+  if (timelineMode !== "source") fail("analysis timeline mode is unsupported");
+  const frameTimes = indices.map((index) => inspection.frameTimes[index]);
+  if (frameTimes.some((value) => typeof value !== "number" || !Number.isFinite(value))) {
+    fail("authoritative frame timestamps must be finite");
+  }
+  return `[sequence]settb=AVTB,setpts=${timestampExpression(frameTimes)}[timed]`;
+}
+
+export function createToolcraftMotionImageAnalysisArguments({
+  indices,
+  inspection,
+  timelineMode = "source",
+}) {
+  validateIndices(inspection, indices);
+  const sequence = sequenceGraph(inspection, indices);
+  const graph = `${sequence.graph};${analysisTimeline(
+    inspection, indices, timelineMode,
+  )};${createToolcraftMotionAnalysisGraph("[timed]", inspection.hasAlpha)}`;
+  return [
+    "-loglevel", "error", "-nostats", ...sequence.args,
+    "-filter_complex", graph,
+    ...createToolcraftMotionAnalysisOutputArguments(inspection.hasAlpha),
+  ];
+}
+
+export function createToolcraftMotionImageMaterializeArguments({
+  inspection,
+  outputPattern,
+  sourceFrameIndices,
+}) {
+  validateIndices(inspection, sourceFrameIndices);
+  if (typeof outputPattern !== "string" || outputPattern.length === 0) {
+    fail("a materialized PNG output pattern is required");
+  }
+  const sequence = sequenceGraph(inspection, sourceFrameIndices);
+  return [
+    "-loglevel", "error", ...sequence.args,
+    "-filter_complex", `${sequence.graph};` +
+      "[sequence]settb=AVTB,setpts=N/TB[materialized]",
+    "-map", "[materialized]", "-fps_mode", "vfr",
+    "-start_number", "0", outputPattern,
+  ];
+}

package/templates/starter/scripts/toolcraft-motion-reference-image-filter-graph.test.mjs

@@ -0,0 +1,124 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  createToolcraftMotionImageAnalysisArguments,
+  createToolcraftMotionImageMaterializeArguments,
+} from "./toolcraft-motion-reference-image-filter-graph.mjs";
+
+function sequenceInspection(overrides = {}) {
+  return {
+    decodedFrameCount: 3,
+    frames: [0, 1, 2].map((sourceFrameIndex) => ({
+      sourceFrameIndex,
+      sourceLocator: `/refs/${sourceFrameIndex}.png`,
+    })),
+    hasAlpha: true,
+    height: 20,
+    inputPath: "/refs",
+    sourceKind: "frame-sequence",
+    timingMode: "ordinal",
+    width: 30,
+    ...overrides,
+  };
+}
+
+const alphaAnalysis = (input = "[timed]") =>
+  `${input}split=2[colorSource][alphaSource];` +
+  "[colorSource]format=yuv444p,signalstats," +
+  "metadata=mode=add:key=toolcraft.channel:value=color," +
+  "metadata=print:file=-[colorout];" +
+  "[alphaSource]alphaextract,format=gray,signalstats," +
+  "metadata=mode=add:key=toolcraft.channel:value=alpha," +
+  "metadata=print:file=-[alphaout]";
+
+test("builds an ordinal image analysis graph with increasing AVTB PTS and 8-bit branches", () => {
+  const args = createToolcraftMotionImageAnalysisArguments({
+    indices: [0, 1, 2],
+    inspection: sequenceInspection(),
+  });
+  const graph = args[args.indexOf("-filter_complex") + 1];
+
+  assert.deepEqual(args.slice(0, 9), [
+    "-loglevel", "error", "-nostats",
+    "-i", "/refs/0.png", "-i", "/refs/1.png", "-i", "/refs/2.png",
+  ]);
+  assert.equal(graph,
+    "[0:v][1:v][2:v]concat=n=3:v=1:a=0[sequence];" +
+    "[sequence]settb=AVTB,setpts=N/TB[timed];" + alphaAnalysis());
+  assert.deepEqual(args.slice(-7), [
+    "-map", "[colorout]", "-map", "[alphaout]", "-f", "null", "-",
+  ]);
+});
+
+test("assigns exact nonuniform authoritative timestamps after ordered concat", () => {
+  const inspection = sequenceInspection({
+    frameTimes: [0, 0.125, 0.5],
+    hasAlpha: false,
+    timingMode: "seconds",
+  });
+  const args = createToolcraftMotionImageAnalysisArguments({
+    indices: [0, 1, 2], inspection,
+  });
+
+  assert.equal(args[args.indexOf("-filter_complex") + 1],
+    "[0:v][1:v][2:v]concat=n=3:v=1:a=0[sequence];" +
+    "[sequence]settb=AVTB," +
+    "setpts='if(eq(N,0),0/TB,if(eq(N,1),0.125/TB,0.5/TB))'[timed];" +
+    "[timed]format=yuv444p,signalstats," +
+    "metadata=mode=add:key=toolcraft.channel:value=color," +
+    "metadata=print:file=-[colorout]");
+});
+
+test("builds the loop comparison in explicit last-to-first order", () => {
+  const args = createToolcraftMotionImageAnalysisArguments({
+    indices: [2, 0],
+    inspection: sequenceInspection(),
+    timelineMode: "loop-seam",
+  });
+  const graph = args[args.indexOf("-filter_complex") + 1];
+
+  assert.deepEqual(args.slice(3, 7), ["-i", "/refs/2.png", "-i", "/refs/0.png"]);
+  assert.equal(graph,
+    "[0:v][1:v]concat=n=2:v=1:a=0[sequence];" +
+    "[sequence]settb=AVTB,setpts=N/TB[timed];" + alphaAnalysis());
+});
+
+test("crops contact-sheet cells before assigning authoritative PTS", () => {
+  const inspection = sequenceInspection({
+    frames: [
+      { cell: { column: 0, row: 0 }, sourceFrameIndex: 0,
+        sourceLocator: "/refs/source#cell=auth.png#cell=0,0" },
+      { cell: { column: 1, row: 0 }, sourceFrameIndex: 1,
+        sourceLocator: "/refs/source#cell=auth.png#cell=1,0" },
+    ],
+    hasAlpha: false,
+    inputPath: "/refs/source#cell=auth.png",
+    sourceKind: "contact-sheet",
+  });
+  const args = createToolcraftMotionImageAnalysisArguments({
+    indices: [0, 1], inspection,
+  });
+
+  assert.deepEqual(args.slice(3, 5), ["-i", "/refs/source#cell=auth.png"]);
+  assert.match(args[args.indexOf("-filter_complex") + 1],
+    /^\[0:v\]crop=w=30:h=20:x=0:y=0\[cell0\];\[0:v\]crop=w=30:h=20:x=30:y=0\[cell1\];/u);
+});
+
+test("materialization preserves selected order without authoritative PTS encoding", () => {
+  const args = createToolcraftMotionImageMaterializeArguments({
+    inspection: sequenceInspection(),
+    outputPattern: "/tmp/review-%06d.png",
+    sourceFrameIndices: [2, 0],
+  });
+
+  assert.deepEqual(args.slice(2, 6), ["-i", "/refs/2.png", "-i", "/refs/0.png"]);
+  assert.equal(args[args.indexOf("-filter_complex") + 1],
+    "[0:v][1:v]concat=n=2:v=1:a=0[sequence];" +
+    "[sequence]settb=AVTB,setpts=N/TB[materialized]");
+  assert.deepEqual(args.slice(-7), [
+    "-map", "[materialized]", "-fps_mode", "vfr",
+    "-start_number", "0", "/tmp/review-%06d.png",
+  ]);
+  assert.equal(args.at(-1), "/tmp/review-%06d.png");
+});

package/templates/starter/scripts/toolcraft-motion-reference-image-source.mjs

@@ -0,0 +1,259 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { createToolcraftSha256 } from "./toolcraft-motion-reference-artifacts.mjs";
+import {
+  createToolcraftMotionLoopSeamScore,
+  createToolcraftMotionProbeArguments,
+  createToolcraftMotionScanResult,
+  validateToolcraftMotionScanRecordAgreement,
+} from "./toolcraft-motion-reference-analysis-protocol.mjs";
+import {
+  normalizeToolcraftMotionToolVersion,
+  parseToolcraftMotionFfprobeJson,
+  parseToolcraftMotionSignalstats,
+} from "./toolcraft-motion-reference-ffmpeg-output.mjs";
+import {
+  createToolcraftMotionImageAnalysisArguments,
+  createToolcraftMotionImageMaterializeArguments,
+} from "./toolcraft-motion-reference-image-filter-graph.mjs";
+import {
+  createToolcraftMotionReviewOutputPath,
+  createToolcraftMotionReviewOutputPattern,
+  validateToolcraftMotionReviewFrameIndices,
+} from "./toolcraft-motion-reference-review-output.mjs";
+import {
+  createToolcraftMotionInputError,
+  createToolcraftMotionStageError,
+  parseToolcraftMotionStage,
+  runToolcraftMotionStage,
+} from "./toolcraft-motion-reference-stage.mjs";
+import {
+  TOOLCRAFT_MOTION_REFERENCE_STAGES,
+} from "./toolcraft-motion-reference-stage-registry.mjs";
+
+const IMAGE_EXTENSIONS = new Set([
+  ".bmp", ".jpeg", ".jpg", ".png", ".tif", ".tiff", ".webp",
+]);
+
+function validateSource(sourceKind, inputPath, execute) {
+  if (sourceKind !== "frame-sequence" && sourceKind !== "contact-sheet") {
+    throw createToolcraftMotionInputError(
+      "Set --kind to frame-sequence or contact-sheet for image sources.",
+    );
+  }
+  if (typeof inputPath !== "string" || inputPath.length === 0) {
+    throw createToolcraftMotionInputError("Provide an absolute image path with --source.");
+  }
+  if (typeof execute !== "function") {
+    throw new TypeError("Toolcraft image source executor is required.");
+  }
+}
+
+function requireBytes(bytes, label) {
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0) {
+    throw createToolcraftMotionInputError(
+      `Choose a ${label} that contains readable image bytes.`,
+    );
+  }
+  return bytes;
+}
+
+async function readSourceBytes(fileSystem, sourcePath) {
+  try {
+    return requireBytes(await fileSystem.readFile(sourcePath), "source");
+  } catch (error) {
+    throw createToolcraftMotionInputError(
+      "Check that --source points to readable image content.", error,
+    );
+  }
+}
+
+async function enumerateSequence(inputPath, fileSystem) {
+  let entries;
+  try {
+    entries = await fileSystem.readdir(inputPath, { withFileTypes: true });
+  } catch (error) {
+    throw createToolcraftMotionInputError(
+      "Check that --source points to a readable frame-sequence directory.", error,
+    );
+  }
+  const relativePaths = entries.flatMap((entry) => {
+    const name = typeof entry === "string" ? entry : entry.name;
+    const isFile = typeof entry === "string" || entry.isFile?.();
+    return isFile && IMAGE_EXTENSIONS.has(path.extname(name).toLowerCase()) ? [name] : [];
+  }).sort();
+  if (relativePaths.length === 0) {
+    throw createToolcraftMotionInputError(
+      "Choose a frame-sequence directory containing at least one supported image.",
+    );
+  }
+  const records = [];
+  for (const relativePath of relativePaths) {
+    const sourceLocator = path.join(inputPath, relativePath);
+    const bytes = await readSourceBytes(fileSystem, sourceLocator);
+    records.push({ bytes, relativePath, sourceLocator });
+  }
+  const identity = records.map(({ bytes, relativePath }) => ({
+    byteLength: bytes.byteLength,
+    relativePath: relativePath.split(path.sep).join("/"),
+    sha256: createToolcraftSha256(bytes),
+  }));
+  return {
+    frames: records.map(({ sourceLocator }, sourceFrameIndex) => ({
+      sourceFrameIndex, sourceLocator,
+    })),
+    probePath: records[0].sourceLocator,
+    sourceSha256: createToolcraftSha256(JSON.stringify(identity)),
+  };
+}
+
+function validateGrid(grid, probe) {
+  if (!grid || !Number.isInteger(grid.columns) || grid.columns <= 0 ||
+      !Number.isInteger(grid.rows) || grid.rows <= 0) {
+    throw createToolcraftMotionInputError(
+      "Provide --grid as positive integer columnsxrows, such as 6x4.",
+    );
+  }
+  if (probe.width % grid.columns !== 0 || probe.height % grid.rows !== 0) {
+    throw createToolcraftMotionInputError(
+      "Choose a --grid that evenly divides the contact-sheet dimensions.",
+    );
+  }
+}
+
+function contactFrames(inputPath, grid) {
+  return Array.from({ length: grid.columns * grid.rows }, (_, sourceFrameIndex) => {
+    const cell = {
+      column: sourceFrameIndex % grid.columns,
+      row: Math.floor(sourceFrameIndex / grid.columns),
+    };
+    return {
+      cell,
+      sourceFrameIndex,
+      sourceLocator: `${inputPath}#cell=${cell.column},${cell.row}`,
+    };
+  });
+}
+
+export async function inspect(input) {
+  if (Object.hasOwn(input ?? {}, "timing")) {
+    throw new TypeError("Toolcraft image timing is applied after intrinsic inspection at the canonical boundary.");
+  }
+  const { execute, fileSystem = fs, grid, inputPath, sourceKind } = input ?? {};
+  validateSource(sourceKind, inputPath, execute);
+  const stage = TOOLCRAFT_MOTION_REFERENCE_STAGES.imageInspect;
+  try {
+    const source = sourceKind === "frame-sequence" ?
+      await enumerateSequence(inputPath, fileSystem) : {
+        probePath: inputPath,
+        sourceBytes: await readSourceBytes(fileSystem, inputPath),
+      };
+    const probed = await runToolcraftMotionStage(execute, {
+      args: createToolcraftMotionProbeArguments(source.probePath), binary: "ffprobe", stage,
+    });
+    const probe = parseToolcraftMotionStage(stage,
+      () => parseToolcraftMotionFfprobeJson(probed.stdout));
+    const version = await runToolcraftMotionStage(execute, {
+      args: ["-version"], binary: "ffmpeg", stage,
+    });
+    const ffmpegVersion = parseToolcraftMotionStage(stage,
+      () => normalizeToolcraftMotionToolVersion(version.stdout, "ffmpeg"));
+    if (sourceKind === "contact-sheet") validateGrid(grid, probe);
+    const frames = sourceKind === "frame-sequence" ? source.frames :
+      contactFrames(inputPath, grid);
+    const dimensions = sourceKind === "contact-sheet" ? {
+      height: probe.height / grid.rows,
+      sourceGrid: { columns: grid.columns, rows: grid.rows },
+      width: probe.width / grid.columns,
+    } : { height: probe.height, width: probe.width };
+    return {
+      decodedFrameCount: frames.length,
+      ffmpegVersion,
+      ffprobeVersion: probe.ffprobeVersion,
+      frames,
+      hasAlpha: probe.hasAlpha,
+      inputPath,
+      pixelFormat: probe.pixelFormat,
+      sourceBasename: path.basename(inputPath),
+      sourceKind,
+      sourceSha256: sourceKind === "frame-sequence" ? source.sourceSha256 :
+        createToolcraftSha256(source.sourceBytes),
+      timingMode: "ordinal",
+      ...dimensions,
+    };
+  } catch (error) {
+    throw createToolcraftMotionStageError(stage, error);
+  }
+}
+
+function parsedStats(stage, stdout, hasAlpha) {
+  return parseToolcraftMotionStage(stage,
+    () => parseToolcraftMotionSignalstats(stdout, { requireAlpha: hasAlpha }));
+}
+
+export async function scan(input) {
+  if (Object.hasOwn(input ?? {}, "sourcePath")) {
+    throw new TypeError("Toolcraft image scan sourcePath is not accepted; use inspection.inputPath.");
+  }
+  const { execute, inspection } = input ?? {};
+  validateSource(inspection?.sourceKind, inspection?.inputPath, execute);
+  const indices = inspection.frames.map((_, index) => index);
+  const scanStage = TOOLCRAFT_MOTION_REFERENCE_STAGES.imageScan;
+  const scanned = await runToolcraftMotionStage(execute, {
+    args: createToolcraftMotionImageAnalysisArguments({ inspection, indices }),
+    binary: "ffmpeg",
+    stage: scanStage,
+  });
+  const records = parsedStats(scanStage, scanned.stdout, inspection.hasAlpha);
+  const expectedTimes = inspection.timingMode === "ordinal" ? indices : inspection.frameTimes;
+  parseToolcraftMotionStage(scanStage,
+    () => validateToolcraftMotionScanRecordAgreement(records, expectedTimes));
+  let seamRecords;
+  if (inspection.decodedFrameCount > 1) {
+    const seamStage = TOOLCRAFT_MOTION_REFERENCE_STAGES.imageLoopSeam;
+    const seam = await runToolcraftMotionStage(execute, {
+      args: createToolcraftMotionImageAnalysisArguments({
+        indices: [indices.at(-1), 0], inspection, timelineMode: "loop-seam",
+      }),
+      binary: "ffmpeg",
+      stage: seamStage,
+    });
+    seamRecords = parsedStats(seamStage, seam.stdout, inspection.hasAlpha);
+  }
+  const seamStage = inspection.decodedFrameCount > 1 ?
+    TOOLCRAFT_MOTION_REFERENCE_STAGES.imageLoopSeam : scanStage;
+  const loopSeamScore = parseToolcraftMotionStage(seamStage,
+    () => createToolcraftMotionLoopSeamScore(
+      inspection.decodedFrameCount, seamRecords,
+    ));
+  return parseToolcraftMotionStage(scanStage,
+    () => createToolcraftMotionScanResult(records, loopSeamScore));
+}
+
+export async function materializeReviewedFrames(input) {
+  if (Object.hasOwn(input ?? {}, "sourcePath")) {
+    throw new TypeError("Toolcraft image materialize sourcePath is not accepted; use inspection.inputPath.");
+  }
+  const { execute, inspection, outputDirectory, sourceFrameIndices } = input ?? {};
+  validateSource(inspection?.sourceKind, inspection?.inputPath, execute);
+  validateToolcraftMotionReviewFrameIndices(
+    sourceFrameIndices, inspection.decodedFrameCount,
+  );
+  const outputPattern = createToolcraftMotionReviewOutputPattern(outputDirectory);
+  await runToolcraftMotionStage(execute, {
+    args: createToolcraftMotionImageMaterializeArguments({
+      inspection, outputPattern, sourceFrameIndices,
+    }),
+    binary: "ffmpeg",
+    stage: TOOLCRAFT_MOTION_REFERENCE_STAGES.imageMaterialize,
+  });
+  return sourceFrameIndices.map((sourceFrameIndex, ordinal) => ({
+    path: createToolcraftMotionReviewOutputPath(outputDirectory, ordinal),
+    sourceFrameIndex,
+    sourceLocator: inspection.frames[sourceFrameIndex].sourceLocator,
+    ...(inspection.timingMode === "seconds" ? {
+      timeSeconds: inspection.frameTimes[sourceFrameIndex],
+    } : {}),
+  }));
+}