@scanmate/merge 0.7.1 → 0.8.0

package/README.md

@@ -58,6 +58,22 @@ Measured on real scans: three 120-dpi page JPEGs plus a 7-page PDF merged in 20
 
 PDF writing uses `@cantoo/pdf-lib`, the maintained fork of pdf-lib, which is pure JavaScript with nothing to install on the host.
 
+## Drawing on a PDF, not just assembling one
+
+The other thing this package writes is marks. `markPages` draws a set of regions on a PDF as vector rectangles, each with its bleed dashed around it, and hands the PDF back:
+
+```ts
+import { markPages } from '@scanmate/merge'
+
+const { pdf, drawn, warnings } = await markPages('issued.pdf', [
+  { page: 1, id: 'signature', x: 120, y: 577, width: 262, height: 22 },
+], { bleedTop: 2, bleedBottom: 12 })
+```
+
+It exists to check that the regions a validation will measure are where the document's fields actually are - most people reach it as `Scanmate.mark` in `@scanmate/scan`, whose README has a worked example on the W-9.
+
+Two things it gets right that a naive version would not. **Rotation and crop box:** a region is in points from the top-left of the page *as displayed*, which is how `@scanmate/extract` reports text, while pdf-lib draws from the bottom-left of the unrotated media box. The conversion between the two is pdf.js's own page transform, ported line for line and inverted, and its spec pins it to values read off real pdf.js for every quarter turn, with and without an offset crop box. **Bleed:** it is resolved by `resolveBleed` from `@scanmate/ink`, the same function the pixel comparison uses, so the band drawn is the band measured.
+
 ## How it decides
 
 [`documentation/algorithms.md`](./documentation/algorithms.md) has the algorithms in full: what each step measures, the decision flows, every constant with the measurement behind it, and what the package deliberately does not do.

package/dist/index.esm.js

@@ -1,5 +1,5 @@
-import { PDFDocument, EncryptedPDFError } from '@cantoo/pdf-lib';
-import { isRaster, decodeImage, readImageMetadata, encodeImage } from '@scanmate/ink';
+import { PDFDocument, EncryptedPDFError, rgb, StandardFonts, degrees } from '@cantoo/pdf-lib';
+import { isRaster, decodeImage, readImageMetadata, encodeImage, resolveBleed, hasBleed, growBy } from '@scanmate/ink';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 
@@ -353,5 +353,200 @@ function embeddableFormat(bytes) {
   return null;
 }
 
-export { MIN_RECORDED_DPI, MergeSourceError, PAPER, isPdf, mergeDocuments, placeImage, readSource, resolveDpi };
+/**
+ * The page as a reader sees it, and the way back to the PDF's own coordinates.
+ *
+ * A mark is measured the way `@scanmate/extract` reports text: from the top-left
+ * of the page as displayed, in points, with the page's `/Rotate` and crop box
+ * already applied. pdf-lib draws in the PDF's own user space instead: from the
+ * bottom-left of the media box, before any rotation.
+ *
+ * Getting from one to the other is the whole difficulty of drawing a mark in
+ * the right place, and doing it approximately would defeat the purpose - a
+ * helper for checking positions that is wrong on rotated or cropped pages gives
+ * false confidence on exactly the pages that most need checking.
+ *
+ * So this is pdf.js's own `PageViewport` transform at scale 1, ported line for
+ * line rather than re-derived, and inverted. The text a mark was measured from
+ * and the box drawn for it then go through the same arithmetic in opposite
+ * directions.
+ */
+/** User space to what a reader sees - pdf.js's `PageViewport` at scale 1. */
+function viewportTransform({
+  view,
+  rotation
+}) {
+  const centerX = (view[2] + view[0]) / 2;
+  const centerY = (view[3] + view[1]) / 2;
+  const [a, b, c, d] = rotationOf(rotation);
+  const quarter = a === 0;
+  const offsetX = quarter ? Math.abs(centerY - view[1]) : Math.abs(centerX - view[0]);
+  const offsetY = quarter ? Math.abs(centerX - view[0]) : Math.abs(centerY - view[1]);
+  return [a, b, c, d, offsetX - a * centerX - c * centerY, offsetY - b * centerX - d * centerY];
+}
+/** How large the page is as a reader sees it: a quarter turn swaps width and height. */
+function viewportSize({
+  view,
+  rotation
+}) {
+  const [a] = rotationOf(rotation);
+  const across = view[2] - view[0];
+  const down = view[3] - view[1];
+  return a === 0 ? {
+    width: down,
+    height: across
+  } : {
+    width: across,
+    height: down
+  };
+}
+/** A point a reader sees, back in the PDF's own coordinates. */
+function toUserSpace([a, b, c, d, e, f], x, y) {
+  const det = a * d - b * c;
+  const dx = x - e;
+  const dy = y - f;
+  // `+ 0` turns a negative zero positive: harmless to draw at, noisy to read back.
+  return {
+    x: (d * dx - c * dy) / det + 0,
+    y: (-b * dx + a * dy) / det + 0
+  };
+}
+/**
+ * pdf.js's rotation matrix for a page turned by `rotation` degrees.
+ *
+ * Only quarter turns are legal in a PDF; anything else is refused here exactly
+ * as pdf.js refuses it, rather than drawn somewhere plausible.
+ */
+function rotationOf(rotation) {
+  const matrix = ROTATIONS.get((rotation % 360 + 360) % 360);
+  if (matrix === undefined) throw new RangeError(`a page may only be rotated by a multiple of 90 degrees, and is rotated by ${rotation}`);
+  return matrix;
+}
+/** pdf.js's `rotateA` to `rotateD`, by quarter turn. */
+const ROTATIONS = new Map([[0, [1, 0, 0, -1]], [90, [0, 1, 1, 0]], [180, [-1, 0, 0, 1]], [270, [0, -1, -1, 0]]]);
+
+/**
+ * The colours of the audit's evidence page, so the two read the same way: the
+ * region in blue, its bleed in magenta.
+ */
+const REGION = rgb(0, 23 / 255, 252 / 255);
+const BLEED = rgb(245 / 255, 0, 252 / 255);
+const LABEL_SIZE = 7;
+/**
+ * Draws each mark on the original, with its bleed around it, and hands the PDF
+ * back - a way to see whether the positions a validation will use are where
+ * the fields actually are, before anything is measured with them.
+ *
+ * Drawn on the document itself, as vectors: the page is not re-rendered, so it
+ * stays sharp at any zoom and the boxes sit exactly where their coordinates
+ * say. Nothing is aligned or adjusted, because there is nothing to align - this
+ * is the original, and the marks were measured against it.
+ */
+async function markPages(pdf, marks, options = {}) {
+  const source = await readSource(pdf, 0);
+  if (source.kind !== 'pdf') throw new TypeError('marks are drawn on a PDF, and this is not one');
+  const document = await PDFDocument.load(source.bytes);
+  const font = options.labels === false ? null : await document.embedFont(StandardFonts.Helvetica);
+  const bleed = resolveBleed(options);
+  const pages = document.getPages();
+  const warnings = [];
+  let drawn = 0;
+  for (const mark of marks) {
+    const name = mark.id ?? `mark ${drawn + warnings.length + 1}`;
+    const page = pages[mark.page - 1];
+    if (page === undefined) {
+      warnings.push(`${name} is on page ${mark.page}, and the document has ${pages.length}`);
+      continue;
+    }
+    const geometry = geometryOf(page);
+    const size = viewportSize(geometry);
+    if (mark.x < 0 || mark.y < 0 || mark.x + mark.width > size.width || mark.y + mark.height > size.height) warnings.push(`${name} reaches past the edge of page ${mark.page}, which is ${round(size.width)} x ${round(size.height)} pt`);
+    // The band first, so the region's own outline draws over it where they meet.
+    if (hasBleed(bleed)) draw(page, geometry, growBy(mark, bleed), {
+      colour: BLEED,
+      dashed: true
+    });
+    draw(page, geometry, mark, {
+      colour: REGION,
+      dashed: false
+    });
+    if (font !== null && mark.id !== undefined) label(page, geometry, font, mark);
+    drawn++;
+  }
+  return {
+    pdf: await document.save(),
+    drawn,
+    warnings
+  };
+}
+/** The page's visible box and rotation, as pdf.js would read them. */
+function geometryOf(page) {
+  const crop = page.getCropBox();
+  return {
+    view: [crop.x, crop.y, crop.x + crop.width, crop.y + crop.height],
+    rotation: page.getRotation().angle
+  };
+}
+/**
+ * A rectangle measured as displayed, drawn in the PDF's own coordinates.
+ *
+ * A quarter turn keeps a rectangle a rectangle, so its corners are taken back
+ * to user space and their extent is the box to draw.
+ */
+function draw(page, geometry, rect, style) {
+  const {
+    x,
+    y,
+    width,
+    height
+  } = userBox(geometry, rect);
+  page.drawRectangle({
+    x,
+    y,
+    width,
+    height,
+    borderColor: style.colour,
+    borderWidth: style.dashed ? 0.6 : 0.9,
+    borderDashArray: style.dashed ? [2.5, 1.5] : undefined,
+    opacity: 0,
+    borderOpacity: 1
+  });
+}
+/**
+ * The id inside the box's top-left corner, upright to the reader however the
+ * page is turned.
+ *
+ * Inside rather than above: on the original a field is empty, so the corner is
+ * free, while the space above it is usually the printed line before - and a
+ * label written over that would obscure the very edge being checked.
+ */
+function label(page, geometry, font, mark) {
+  const at = toUserSpace(viewportTransform(geometry), mark.x + 2, mark.y + LABEL_SIZE);
+  page.drawText(mark.id ?? '', {
+    x: at.x,
+    y: at.y,
+    size: LABEL_SIZE,
+    font,
+    color: REGION,
+    // Text is laid in user space; turning it with the page keeps it readable.
+    rotate: degrees(geometry.rotation)
+  });
+}
+function userBox(geometry, rect) {
+  const transform = viewportTransform(geometry);
+  const corners = [toUserSpace(transform, rect.x, rect.y), toUserSpace(transform, rect.x + rect.width, rect.y + rect.height)];
+  const xs = corners.map(corner => corner.x);
+  const ys = corners.map(corner => corner.y);
+  return {
+    x: Math.min(...xs),
+    y: Math.min(...ys),
+    width: Math.abs(xs[1] - xs[0]),
+    height: Math.abs(ys[1] - ys[0])
+  };
+}
+function round(value) {
+  return Math.round(value * 10) / 10;
+}
+
+export { MIN_RECORDED_DPI, MergeSourceError, PAPER, isPdf, markPages, mergeDocuments, placeImage, readSource, resolveDpi, toUserSpace, viewportSize, viewportTransform };
 //# sourceMappingURL=index.esm.js.map

package/dist/src/index.d.ts

@@ -23,9 +23,13 @@ export { mergeDocuments } from './document-merge/index.js';
 export type { Embedding, MergedPage, MergeOptions, MergeResult } from './document-merge/index.js';
 export { MergeSourceError } from './source-reading/index.js';
 export type { SourceKind } from './source-reading/index.js';
+export { markPages } from './page-marking/index.js';
+export type { MarkOptions, MarkResult, PageMark } from './page-marking/index.js';
 export type { PageSize } from './page-placement/index.js';
 export { MIN_RECORDED_DPI, PAPER, placeImage, resolveDpi } from './page-placement/index.js';
 export type { Placement } from './page-placement/index.js';
 export { isPdf, readSource } from './source-reading/index.js';
 export type { ResolvedSource } from './source-reading/index.js';
+export { toUserSpace, viewportSize, viewportTransform } from './page-marking/index.js';
+export type { Affine, PageGeometry } from './page-marking/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/page-marking/index.d.ts

@@ -0,0 +1,6 @@
+/** Drawing expected regions on the original, to see whether they are where the fields are. */
+export { markPages } from './mark-pages.use-case.js';
+export type { MarkOptions, MarkResult, PageMark } from './page-mark.contract.js';
+export { toUserSpace, viewportSize, viewportTransform } from './page-viewport.policy.js';
+export type { Affine, PageGeometry } from './page-viewport.policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/page-marking/mark-pages.use-case.d.ts

@@ -0,0 +1,14 @@
+import type { ScanmateBinarySource } from '@scanmate/ink';
+import type { MarkOptions, MarkResult, PageMark } from './page-mark.contract.js';
+/**
+ * Draws each mark on the original, with its bleed around it, and hands the PDF
+ * back - a way to see whether the positions a validation will use are where
+ * the fields actually are, before anything is measured with them.
+ *
+ * Drawn on the document itself, as vectors: the page is not re-rendered, so it
+ * stays sharp at any zoom and the boxes sit exactly where their coordinates
+ * say. Nothing is aligned or adjusted, because there is nothing to align - this
+ * is the original, and the marks were measured against it.
+ */
+export declare function markPages(pdf: ScanmateBinarySource, marks: readonly PageMark[], options?: MarkOptions): Promise<MarkResult>;
+//# sourceMappingURL=mark-pages.use-case.d.ts.map

package/dist/src/page-marking/page-mark.contract.d.ts

@@ -0,0 +1,40 @@
+import type { Bleed, ScanmateRect } from '@scanmate/ink';
+/**
+ * One region to draw, where the document's own fields are expected to be.
+ *
+ * In points, from the top-left of the page as displayed - the same coordinates
+ * `@scanmate/extract` reports text in, and the same shape as `@scanmate/diff`'s
+ * `ExpectedChange`. So the array about to be handed to an audit can be drawn
+ * as it is, and what is checked visually is exactly what will be measured.
+ */
+export interface PageMark extends ScanmateRect {
+    /** One-based page number. */
+    page: number;
+    /** Written beside the box, so a reviewer can tell which field is which. */
+    id?: string;
+}
+/**
+ * How the marks are drawn. The bleed - `bleed`, and `bleedTop`, `bleedRight`,
+ * `bleedBottom`, `bleedLeft` to override a side - is drawn as a dashed band
+ * around each mark, and is the same rule the pixel comparison measures with. A
+ * mark checked here with a given bleed is checked against the region an audit
+ * with that bleed will actually claim. Default 6 points on every side.
+ */
+export interface MarkOptions extends Bleed {
+    /** Write each mark's `id` beside it. Default `true`. */
+    labels?: boolean;
+}
+export interface MarkResult {
+    /** The original, with the marks drawn on it. Nothing else about it changes. */
+    pdf: Uint8Array;
+    /** How many marks were drawn. */
+    drawn: number;
+    /**
+     * What could not be drawn, or was drawn somewhere it cannot be right: a mark
+     * on a page the document does not have, or one that reaches past the edge of
+     * its page. The second is itself a positioning error, and exactly the kind
+     * this exists to catch.
+     */
+    warnings: string[];
+}
+//# sourceMappingURL=page-mark.contract.d.ts.map

package/dist/src/page-marking/page-viewport.policy.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The page as a reader sees it, and the way back to the PDF's own coordinates.
+ *
+ * A mark is measured the way `@scanmate/extract` reports text: from the top-left
+ * of the page as displayed, in points, with the page's `/Rotate` and crop box
+ * already applied. pdf-lib draws in the PDF's own user space instead: from the
+ * bottom-left of the media box, before any rotation.
+ *
+ * Getting from one to the other is the whole difficulty of drawing a mark in
+ * the right place, and doing it approximately would defeat the purpose - a
+ * helper for checking positions that is wrong on rotated or cropped pages gives
+ * false confidence on exactly the pages that most need checking.
+ *
+ * So this is pdf.js's own `PageViewport` transform at scale 1, ported line for
+ * line rather than re-derived, and inverted. The text a mark was measured from
+ * and the box drawn for it then go through the same arithmetic in opposite
+ * directions.
+ */
+/** A two-dimensional affine transform, `[a, b, c, d, e, f]` as PDF writes them. */
+export type Affine = readonly [number, number, number, number, number, number];
+/** The page's visible box, `[x0, y0, x1, y1]` in user space, and its rotation. */
+export interface PageGeometry {
+    view: readonly [number, number, number, number];
+    rotation: number;
+}
+/** User space to what a reader sees - pdf.js's `PageViewport` at scale 1. */
+export declare function viewportTransform({ view, rotation }: PageGeometry): Affine;
+/** How large the page is as a reader sees it: a quarter turn swaps width and height. */
+export declare function viewportSize({ view, rotation }: PageGeometry): {
+    width: number;
+    height: number;
+};
+/** A point a reader sees, back in the PDF's own coordinates. */
+export declare function toUserSpace([a, b, c, d, e, f]: Affine, x: number, y: number): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=page-viewport.policy.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scanmate/merge",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Merge PDFs, images and rasters into one PDF: PDF pages copied as they are, JPEGs embedded without recompression, every page of a TIFF.",
   "license": "MIT",
   "author": "Eduardo Russo",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "@cantoo/pdf-lib": "^2.11.1",
-    "@scanmate/ink": "^0.7.1"
+    "@scanmate/ink": "^0.8.0"
   },
   "publishConfig": {
     "access": "public"