@scanmate/diff 0.1.0 → 0.2.1

package/README.md

@@ -26,11 +26,13 @@ const changes = await diffPages(await alignPages(pages), [
   { page: 1, id: 'date',      x: 404, y: 577, width: 171, height: 22 },
 ], { sideBySide: true })
 
-changes[0].expected          // [{ id, identified, addedInk, overfilled, ink: { ... } }]
-changes[0].unexpected        // [{ x, y, width, height, inkArea, pixels }]
-changes[0].missing           // printed ink the scan lost
-changes[0].sideBySideImage   // original and scan, boxed alike
-changes[0].diffImage         // the overlay: violet where the ink differs, grey where it agrees
+// Every page comes back carrying its comparison, so nothing has to be matched
+// up again by index - and everything the page already had is still on it.
+changes[0].diff.expected     // [{ id, identified, addedInk, overfilled, ink: { ... } }]
+changes[0].diff.unexpected   // [{ x, y, width, height, inkArea, pixels }]
+changes[0].diff.missing      // printed ink the scan lost
+changes[0].diff.diffImage    // the overlay: violet where the ink differs, grey where it agrees
+changes[0].aligned.raster    // still the page you handed in
 ```
 
 Rectangles are in PDF points from the page's top-left by default, the same frame `@scanmate/extract` reports text in; `units: 'pixels'` switches to the original's rendered pixels.

package/dist/index.esm.js

@@ -686,7 +686,10 @@ async function diffPages(pages, expected = [], options = {}) {
       ...options,
       probes: (options.probes ?? []).filter(probe => probe.page === undefined || probe.page === page.page)
     });
-    results.push(result);
+    results.push({
+      ...page,
+      diff: result
+    });
     onProgress?.({
       stage: 'diff',
       phase: 'done',

package/dist/src/change-detection/annotate-overlay.use-case.d.ts

@@ -1,4 +1,4 @@
-import type { Raster, Rect, Rgba } from '@scanmate/ink';
+import type { Raster, ScanmateRect, Rgba } from '@scanmate/ink';
 /**
  * Outline what the report says onto the overlay, so the picture and the numbers
  * can be checked against each other at a glance.
@@ -30,7 +30,7 @@ export declare const EXPECTED_MARGIN: Rgba;
 export declare const UNEXPECTED: Rgba;
 export declare const MISSING: Rgba;
 export interface Annotation {
-    rect: Rect;
+    rect: ScanmateRect;
     color: Rgba;
 }
 export declare function annotateOverlay(overlay: Raster, annotations: readonly Annotation[], thickness?: number): void;

package/dist/src/change-detection/diff-pages.use-case.d.ts

@@ -1,5 +1,5 @@
 import type { AlignedPage } from '@scanmate/ink';
-import type { DiffOptions, ExpectedChange, PageDiff } from './page-diff.contract.js';
+import type { ComparedPage, DiffOptions, ExpectedChange, PageDiff } from './page-diff.contract.js';
 /**
  * What changed on each page, and whether it was supposed to.
  *
@@ -16,7 +16,7 @@ import type { DiffOptions, ExpectedChange, PageDiff } from './page-diff.contract
  * Masks are built once per page and read four ways: the overlay, the expected
  * regions, the added changes and the missing ones.
  */
-export declare function diffPages(pages: readonly AlignedPage[], expected?: readonly ExpectedChange[], options?: DiffOptions): Promise<PageDiff[]>;
+export declare function diffPages<Page extends AlignedPage>(pages: readonly Page[], expected?: readonly ExpectedChange[], options?: DiffOptions): Promise<Array<ComparedPage<Page>>>;
 /** One page. `expected` should already be the regions for this page. */
 export declare function diffPage(page: AlignedPage, expected?: readonly ExpectedChange[], options?: DiffOptions): Promise<PageDiff>;
 //# sourceMappingURL=diff-pages.use-case.d.ts.map

package/dist/src/change-detection/index.d.ts

@@ -9,7 +9,7 @@ export type { Component, LabelledComponents, LabelOptions } from './connected-co
 export { diffPage, diffPages } from './diff-pages.use-case.js';
 export { mergeBoxes } from './merge-boxes.use-case.js';
 export type { MergedBox } from './merge-boxes.use-case.js';
-export type { Change, CoordinateUnits, DiffOptions, ExpectedChange, ExpectedResult, InkProbe, PageDiff, ProbeRect, RegionInkMetrics } from './page-diff.contract.js';
+export type { Change, ComparedPage, CoordinateUnits, DiffOptions, ExpectedChange, ExpectedResult, InkProbe, PageDiff, ProbeRect, RegionInkMetrics } from './page-diff.contract.js';
 export { measureRegionInk } from './region-ink.use-case.js';
 export type { RegionInk, RegionInkOptions } from './region-ink.use-case.js';
 export { composeSideBySide } from './side-by-side.use-case.js';

package/dist/src/change-detection/page-diff.contract.d.ts

@@ -1,4 +1,4 @@
-import type { ImageFormat, InkOptions, ProgressCallback, Raster, Rect } from '@scanmate/ink';
+import type { AlignedPage, ImageFormat, InkOptions, ProgressCallback, Raster, ScanmateRect } from '@scanmate/ink';
 import type { Masks } from '../region-comparison/index.js';
 /**
  * Coordinates for regions going in and changes coming out.
@@ -20,6 +20,19 @@ export interface ExpectedChange {
     width: number;
     height: number;
 }
+/**
+ * An aligned page with what the pixel comparison found on it.
+ *
+ * The comparison hands the page back rather than a bare result, so whatever the
+ * producer attached - the metadata, the page's partner in the scan, anything a
+ * caller added - is still there afterwards. A bare result carries only a page
+ * number, and matching those up again is a join the caller should never have to
+ * write: page numbers are the original's, and go non-contiguous the moment
+ * anyone extracts `'1-3,5'`.
+ */
+export type ComparedPage<Page extends AlignedPage = AlignedPage> = Page & {
+    diff: PageDiff;
+};
 export interface DiffOptions {
     /** Units of `ExpectedChange` rectangles and of every rectangle reported back. Default `'points'`. */
     units?: CoordinateUnits;
@@ -179,7 +192,7 @@ export interface RegionInkMetrics {
     /** Ink in the largest change, in square millimetres. */
     largestArea: number;
     /** Box around all of it, in the requested units; `null` when there is none. */
-    bounds: Rect | null;
+    bounds: ScanmateRect | null;
     /** `bounds` as a share of the region's width and height. */
     widthRatio: number;
     heightRatio: number;
@@ -196,13 +209,13 @@ export interface RegionInkMetrics {
 }
 /** A change found where nothing was expected, or ink that went missing. */
 /** A place to measure the ink at; `page` selects the page when several are compared. */
-export type ProbeRect = Rect & {
+export type ProbeRect = ScanmateRect & {
     page?: number;
 };
 /** What the ink does inside one place that was asked about. */
 export interface InkProbe {
     /** The place asked about, in `units`. */
-    rect: Rect;
+    rect: ScanmateRect;
     /** New ink there, in square millimetres. */
     addedInk: number;
     /** Printed ink lost there, in square millimetres. */

package/dist/src/change-detection/probe-ink.use-case.d.ts

@@ -1,4 +1,4 @@
-import type { Rect } from '@scanmate/ink';
+import type { ScanmateRect } from '@scanmate/ink';
 import type { Masks } from '../region-comparison/index.js';
 import type { CoordinateUnits, InkProbe } from './page-diff.contract.js';
 /**
@@ -19,12 +19,12 @@ import type { CoordinateUnits, InkProbe } from './page-diff.contract.js';
  * @param options - How to read `rects`, and the resolution they are in.
  * @returns One probe per rectangle, in the same order, in square millimetres.
  */
-export declare function probeInk(masks: Masks, rects: readonly Rect[], options?: {
+export declare function probeInk(masks: Masks, rects: readonly ScanmateRect[], options?: {
     dpi?: number;
     units?: CoordinateUnits;
 }): InkProbe[];
 /** Added, lost and shared ink inside one rectangle of the page, in pixels. */
-export declare function inkWithin(rect: Rect, masks: Masks): {
+export declare function inkWithin(rect: ScanmateRect, masks: Masks): {
     added: number;
     lost: number;
     shared: number;

package/dist/src/change-detection/region-ink.use-case.d.ts

@@ -1,4 +1,4 @@
-import type { BinaryImage, Rect } from '@scanmate/ink';
+import type { BinaryImage, ScanmateRect } from '@scanmate/ink';
 /**
  * The shape of the new ink inside one expected region.
  *
@@ -34,7 +34,7 @@ export interface RegionInk {
     /** Pixels in the largest one. */
     largest: number;
     /** Box around every change that counts, in page pixels; `null` when there is none. */
-    bounds: Rect | null;
+    bounds: ScanmateRect | null;
     /** Share of those pixels that lie in the band along the region's border. */
     edgeTouch: number;
     /** Share of the region's area that is counted new ink. */
@@ -43,5 +43,5 @@ export interface RegionInk {
     formLines: number;
 }
 /** Analyse `added` (the page's new-ink mask) inside `rect` (page pixels). */
-export declare function measureRegionInk(added: BinaryImage, rect: Rect, options: RegionInkOptions): RegionInk;
+export declare function measureRegionInk(added: BinaryImage, rect: ScanmateRect, options: RegionInkOptions): RegionInk;
 //# sourceMappingURL=region-ink.use-case.d.ts.map

package/dist/src/index.d.ts

@@ -15,7 +15,7 @@
  * different part of the page in each image.
  */
 export { diffPage, diffPages } from './change-detection/index.js';
-export type { Change, CoordinateUnits, DiffOptions, ExpectedChange, ExpectedResult, InkProbe, PageDiff, ProbeRect, RegionInkMetrics } from './change-detection/index.js';
+export type { Change, ComparedPage, CoordinateUnits, DiffOptions, ExpectedChange, ExpectedResult, InkProbe, PageDiff, ProbeRect, RegionInkMetrics } from './change-detection/index.js';
 export { compareRegions, diffDocument, renderDiff } from './region-comparison/index.js';
 export type { DocumentDiff, Region, RegionOptions, RegionReport } from './region-comparison/index.js';
 export { annotateOverlay, composePanels, composeSideBySide, connectedComponents, EXPECTED_MARGIN, IDENTIFIED, labelComponents, measureRegionInk, mergeBoxes, MISSING, NOT_IDENTIFIED, probeInk, REFERENCE, UNEXPECTED, UNSETTLED } from './change-detection/index.js';

package/dist/src/region-comparison/compare-regions.use-case.d.ts

@@ -1,4 +1,4 @@
-import type { ImageInput } from '@scanmate/ink';
+import type { ScanmateSource } from '@scanmate/ink';
 import type { Masks } from './ink-masks.use-case.js';
 import type { DocumentDiff, Region, RegionOptions, RegionReport } from './region.model.js';
 /**
@@ -23,9 +23,9 @@ import type { DocumentDiff, Region, RegionOptions, RegionReport } from './region
  * original's canvas. Feeding a raw scan in produces confident nonsense, because
  * every rectangle then names a different part of the page in each image.
  */
-export declare function compareRegions(original: ImageInput, aligned: ImageInput, regions: readonly Region[], options?: RegionOptions): Promise<RegionReport[]>;
+export declare function compareRegions(original: ScanmateSource, aligned: ScanmateSource, regions: readonly Region[], options?: RegionOptions): Promise<RegionReport[]>;
 /** Page-wide added/removed ink, plus per-region detail for any regions supplied. */
-export declare function diffDocument(original: ImageInput, aligned: ImageInput, regions?: readonly Region[], options?: RegionOptions): Promise<DocumentDiff>;
+export declare function diffDocument(original: ScanmateSource, aligned: ScanmateSource, regions?: readonly Region[], options?: RegionOptions): Promise<DocumentDiff>;
 /** One region's added and removed ink, from masks already built. */
 export declare function measureRegion(region: Region, masks: Masks, defaultThreshold: number): RegionReport;
 //# sourceMappingURL=compare-regions.use-case.d.ts.map

package/dist/src/region-comparison/ink-masks.use-case.d.ts

@@ -1,4 +1,4 @@
-import type { BinaryImage, ImageInput, InkOptions } from '@scanmate/ink';
+import type { BinaryImage, ScanmateSource, InkOptions } from '@scanmate/ink';
 /**
  * The ink masks every comparison starts from, plus their tolerance bands.
  *
@@ -32,5 +32,5 @@ export interface Masks {
 }
 /** Default for {@link buildMasks}' `faintInk`, measured against real scans. */
 export declare const FAINT_INK = 0.25;
-export declare function buildMasks(original: ImageInput, aligned: ImageInput, ink: InkOptions | undefined, tolerance: number, faintInk?: number): Promise<Masks>;
+export declare function buildMasks(original: ScanmateSource, aligned: ScanmateSource, ink: InkOptions | undefined, tolerance: number, faintInk?: number): Promise<Masks>;
 //# sourceMappingURL=ink-masks.use-case.d.ts.map

package/dist/src/region-comparison/region.model.d.ts

@@ -1,8 +1,8 @@
-import type { InkOptions, Rect } from '@scanmate/ink';
+import type { InkOptions, ScanmateRect } from '@scanmate/ink';
 export interface Region {
     id: string;
     /** In the *original's* pixel coordinates - the whole point of aligning first. */
-    rect: Rect;
+    rect: ScanmateRect;
     /** Fraction of the region that must be new ink before `filled` is true. Overrides the global default. */
     threshold?: number;
 }
@@ -24,7 +24,7 @@ export interface RegionOptions {
 }
 export interface RegionReport {
     id: string;
-    rect: Rect;
+    rect: ScanmateRect;
     /** Ink coverage of the region in the original, in `[0, 1]`. */
     originalInk: number;
     /** Ink coverage of the region in the aligned scan. */

package/dist/src/region-comparison/render-diff.use-case.d.ts

@@ -1,4 +1,4 @@
-import type { ImageInput, Raster, Rgba } from '@scanmate/ink';
+import type { ScanmateSource, Raster, Rgba } from '@scanmate/ink';
 import type { Masks } from './ink-masks.use-case.js';
 import type { RegionOptions } from './region.model.js';
 /**
@@ -14,7 +14,7 @@ import type { RegionOptions } from './region.model.js';
  * measured separately and in millimetres. Here it would be a second colour
  * carrying a distinction the eye does not need at this zoom.
  */
-export declare function renderDiff(original: ImageInput, aligned: ImageInput, options?: RegionOptions): Promise<Raster>;
+export declare function renderDiff(original: ScanmateSource, aligned: ScanmateSource, options?: RegionOptions): Promise<Raster>;
 /**
  * Ink the two pages do not share. Violet rather than red, because red means
  * "changed" on every annotated page in the pipeline and one colour cannot mean

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scanmate/diff",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "What changed between an original and its aligned scan: expected regions filled in, unexpected marks, lost ink, and a side-by-side evidence image.",
   "license": "MIT",
   "author": "Eduardo Russo",
@@ -39,12 +39,12 @@
     "!**/*.js.map"
   ],
   "dependencies": {
-    "@scanmate/ink": "^0.1.0"
+    "@scanmate/ink": "^0.2.1"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@scanmate/align": "^0.1.0"
+    "@scanmate/align": "^0.2.1"
   }
 }