@scanmate/diff 0.7.1 → 0.8.0

package/README.md

@@ -48,7 +48,9 @@ Rectangles are in PDF points from the page's top-left by default, the same frame
 
 A region is **identified** when it has at least `minFillArea` (2 mm²) of new ink and is not **overfilled** — covered or struck through, which `maxFill` (0.5) draws the line on. Form rules showing through a slight misregistration are discounted: a component spanning 90% of the region and no thicker than 0.6 mm is the box's own printed line.
 
-People sign past the box they are given, so each region also claims the ink within `expectedMargin` (6 points) of it, and the regions claim it **together**, so one stroke running through two fields is not left over as an unexpected mark. What a region reports is still the rectangle it was given; the band is drawn in pink.
+People sign past the box they are given, so each region also claims the ink within its **bleed** - 6 points on every side unless told otherwise - and the regions claim it **together**, so one stroke running through two fields is not left over as an unexpected mark. What a region reports is still the rectangle it was given; the band is drawn in pink.
+
+The bleed can be set per side: `bleed` for all four, and `bleedTop`, `bleedRight`, `bleedBottom` or `bleedLeft` to override one. A signature descends more than it climbs, so `{ bleedTop: 2, bleedBottom: 12 }` keeps a field clear of the printed line above it and gives the pen room below. `Scanmate.mark` in `@scanmate/scan` draws exactly this band on the original, so a region can be checked before anything is measured with it.
 
 Each region reports its shape too — how many separate changes, the largest, the bounds as a share of the box, how much ink touches the border — so a signature can be told from a stray line without looking at the picture.
 
@@ -61,7 +63,7 @@ Each region reports its shape too — how many separate changes, the largest, th
 | `faintInk` | `0.25` | Fraction of the normal threshold for "still there". |
 | `minFillArea` | `2` mm² | New ink a region needs. |
 | `maxFill` | `0.5` | Above this the region is covered, not filled. |
-| `expectedMargin` | `6` pt | How far outside a region its ink may lie. |
+| `bleed` | `6` pt | How far outside a region its ink may lie, every side. `bleedTop`, `bleedRight`, `bleedBottom` and `bleedLeft` override one side. |
 | `formLineSpan` | `0.9` | Span that makes a component a printed rule... |
 | `formLineThickness` | `0.6` mm | ...if it is no thicker than this. |
 | `minChangeArea` | `1` mm² | Smallest change reported. |

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-import { createRaster, decodeImage, binarize, inkMap, toGrayscale, otsuThreshold, dilate, coverage, encodeImage } from '@scanmate/ink';
+import { createRaster, decodeImage, binarize, inkMap, toGrayscale, otsuThreshold, dilate, coverage, resolveBleed, growBy, hasBleed, encodeImage } from '@scanmate/ink';
 
 /** The area in question, drawn on the original: a statement of where, not of what. */
 const REFERENCE = [0, 23, 252, 255];
@@ -720,7 +720,6 @@ async function diffPage(page, expected = [], options = {}) {
     mergeGap = 3,
     assumeDpi = 150,
     regionOverlap = 0.5,
-    expectedMargin = 6,
     maxChanges = 50,
     probes = [],
     keepMasks = false,
@@ -736,10 +735,11 @@ async function diffPage(page, expected = [], options = {}) {
   const masks = await buildMasks(page.original.raster, page.aligned.raster, ink, tolerance, faintInk);
   // People sign past the box they are given, so each region claims the ink a little
   // way outside it too; what it reports is still the region it was given.
+  const bleed = resolveBleed(options);
   const regions = expected.map(e => ({
     id: e.id,
     rect: scaleRect(e, toPixels),
-    claim: scaleRect(grow(e, expectedMargin), toPixels)
+    claim: scaleRect(growBy(e, bleed), toPixels)
   }));
   const findChanges = (mask, minArea) => {
     const components = connectedComponents(mask).filter(c => c.pixels >= 2);
@@ -806,28 +806,28 @@ async function diffPage(page, expected = [], options = {}) {
   const unexpected = outside.slice(0, maxChanges).map(box => toChange(box));
   const missing = lost.slice(0, maxChanges).map(box => toChange(box));
   // The band first, so a region's own outline draws over it where they meet.
-  const margins = expectedMargin > 0 ? regions.map(region => ({
+  const margins = hasBleed(bleed) ? regions.map(region => ({
     rect: region.claim,
     color: EXPECTED_MARGIN
   })) : [];
   const verdicts = regions.map((region, i) => ({
-    rect: grow(region.rect, 2),
+    rect: pad(region.rect, 2),
     color: expectedResults[i].identified ? IDENTIFIED : NOT_IDENTIFIED
   }));
   const reported = [...margins, ...verdicts, ...outside.slice(0, maxChanges).map(box => ({
-    rect: grow(box, 4),
+    rect: pad(box, 4),
     color: UNEXPECTED
   }))];
   // On the original, every region is simply the area in question; the answers belong to the scan.
   const asAsked = regions.map(region => ({
-    rect: grow(region.rect, 2),
+    rect: pad(region.rect, 2),
     color: REFERENCE
   }));
   const diffRaster = paintOverlay(masks);
   if (annotate) annotateOverlay(diffRaster, reported);
   // Lines about a point thick at any dpi, so the boxes read the same on every page.
   const losses = lost.slice(0, maxChanges).map(box => ({
-    rect: grow(box, 4),
+    rect: pad(box, 4),
     color: MISSING
   }));
   const sideBySideRaster = sideBySide ? composeSideBySide(page.original.raster, page.aligned.raster, {
@@ -925,7 +925,12 @@ function scaleRect(rect, factor) {
     height: rect.height * factor
   };
 }
-function grow(rect, by) {
+/**
+ * A box drawn a little outside what it marks, in pixels, so the outline does not
+ * cover the ink it is pointing at. Purely how the evidence is drawn; the room a
+ * region is allowed is its bleed, and that is decided by `resolveBleed`.
+ */
+function pad(rect, by) {
   return {
     x: rect.x - by,
     y: rect.y - by,

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

@@ -1,4 +1,4 @@
-import type { AlignedPage, ImageFormat, InkOptions, ProgressCallback, Raster, ScanmateRect } from '@scanmate/ink';
+import type { AlignedPage, Bleed, 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.
@@ -33,7 +33,24 @@ export interface ExpectedChange {
 export type ComparedPage<Page extends AlignedPage = AlignedPage> = Page & {
     diff: PageDiff;
 };
-export interface DiffOptions {
+/**
+ * How the comparison is run.
+ *
+ * The bleed - `bleed`, and `bleedTop`, `bleedRight`, `bleedBottom`, `bleedLeft`
+ * to override a side - is how far outside an expected region its ink may still
+ * lie, in `units`. Default 6 on every side, 2 mm at 72 points to the inch.
+ *
+ * People sign past the box they are given - a descender below the rule, a
+ * flourish out to the side - and that is the signature, not a mark someone made
+ * elsewhere. The region claims the ink within its bleed and measures it, while
+ * still reporting the rectangle it was given. Ink inside the bleed of any
+ * expected region counts towards them all, so one stroke crossing two fields is
+ * not left over as unexpected.
+ *
+ * It is the same rule `Scanmate.mark` draws, so the band a reviewer is shown is
+ * the band that is measured.
+ */
+export interface DiffOptions extends Bleed {
     /** Units of `ExpectedChange` rectangles and of every rectangle reported back. Default `'points'`. */
     units?: CoordinateUnits;
     /**
@@ -56,17 +73,6 @@ export interface DiffOptions {
      * 150 dpi, so a caller is expected to drop them as soon as it has asked.
      */
     keepMasks?: boolean;
-    /**
-     * How far outside an expected region its ink may still lie, in `units`. Default `6`
-     * (2 mm at 72 points to the inch).
-     *
-     * People sign past the box they are given - a descender below the rule, a flourish
-     * out to the side - and that is the signature, not a mark someone made elsewhere. The
-     * region claims the ink within this band and measures it, while still reporting the
-     * rectangle it was given. Ink inside the band of any expected region counts towards
-     * them all, so one stroke crossing two fields is not left over as unexpected.
-     */
-    expectedMargin?: number;
     /** Pixels the original's ink is fattened by before diffing, to absorb sub-pixel misalignment. Default `2`. */
     tolerance?: number;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scanmate/diff",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "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.7.1"
+    "@scanmate/ink": "^0.8.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@scanmate/align": "^0.7.1"
+    "@scanmate/align": "^0.8.0"
   }
 }