@parseo/appraisals 1.0.0

package/README.md

@@ -0,0 +1,35 @@
+# @parseo/appraisals
+
+Deterministic PDF parsers for appraisal reports. Supports Richer Values, Form 1004-MC (URAR), and Form 1073 (Condo).
+
+## Installation
+
+```bash
+npm install @parseo/appraisals
+```
+
+## Usage
+
+```typescript
+import { richerValues, form1004MC, form1073 } from "@parseo/appraisals";
+
+const report = await richerValues(buffer); // RicherValuesReport
+const report = await form1004MC(buffer);   // Form1004MCReport
+const report = await form1073(buffer);     // Form1073Report
+```
+
+| Format | Import name |
+|---|---|
+| Richer Values | `richerValues` |
+| Form 1004-MC (URAR) | `form1004MC` |
+| Form 1073 (Condo) | `form1073` |
+
+## Data conventions
+
+- **Dates**: ISO 8601 strings (`"2024-08-31"`) or `null`
+- **Currency**: Plain numbers (`54961.89`, not `"$54,961.89"`)
+- **Bounding boxes**: `{ x, y, width, height, pageNumber }` on every extracted field
+
+## License
+
+MIT

package/dist/form-1004mc/extract-checkboxes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Checkbox extraction from PDF vector graphics.
+ *
+ * In flattened TOTAL-generated PDFs, checkbox marks are rendered as
+ * constructPath operations (small ~8.4×8.4 pt shapes). An unchecked
+ * checkbox produces 1 path (the empty square outline). A checked
+ * checkbox produces 5 paths (square outline + 4 X-mark line segments).
+ *
+ * We exploit this by counting how many path shapes fall at each
+ * position — ≥ 3 means checked.
+ */
+export interface CheckedPosition {
+    /** x of the checkbox square (left edge) */
+    x: number;
+    /** y in top-down text coordinates (matches TextLine.y) */
+    y: number;
+}
+/**
+ * Extract all checked checkbox positions from a given PDF page.
+ *
+ * @returns Array of {x, y} positions where a checkbox is checked,
+ *          in the same coordinate space as extracted TextLine objects.
+ */
+export declare function extractCheckedBoxes(buffer: Buffer, pageNum: number): Promise<CheckedPosition[]>;
+/**
+ * Given a list of checked positions and a set of checkbox options
+ * at known x-positions on a given text-y row, return which option is checked.
+ *
+ * The checkbox square is rendered ~7pt above the text label (lower y value
+ * in top-down coordinates) and ~12pt to its left. Since rows are only
+ * ~11pt apart, we use a directional y-match: the checkbox must be above
+ * the text line (yDiff in [2, 12]) to avoid cross-row false positives.
+ *
+ * @param checked - Array of checked checkbox positions
+ * @param textY - The y-coordinate of the text row (from TextLine.y)
+ * @param options - Map of checkbox x-position to option label
+ * @param xTolerance - x-axis matching tolerance in points (default 6)
+ */
+export declare function resolveCheckbox(checked: CheckedPosition[], textY: number, options: {
+    x: number;
+    label: string;
+}[], xTolerance?: number): string;
+//# sourceMappingURL=extract-checkboxes.d.ts.map

package/dist/form-1004mc/extract-checkboxes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-checkboxes.d.ts","sourceRoot":"","sources":["../../src/form-1004mc/extract-checkboxes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqBH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,CAAC,EAAE,MAAM,CAAC;IACV,0DAA0D;IAC1D,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,EAAE,CAAC,CAgG5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,EACvC,UAAU,SAAI,GACb,MAAM,CAWR"}

package/dist/form-1004mc/extract-checkboxes.js

@@ -0,0 +1,145 @@
+/**
+ * Checkbox extraction from PDF vector graphics.
+ *
+ * In flattened TOTAL-generated PDFs, checkbox marks are rendered as
+ * constructPath operations (small ~8.4×8.4 pt shapes). An unchecked
+ * checkbox produces 1 path (the empty square outline). A checked
+ * checkbox produces 5 paths (square outline + 4 X-mark line segments).
+ *
+ * We exploit this by counting how many path shapes fall at each
+ * position — ≥ 3 means checked.
+ */
+import { OPS, getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+function multiply(a, b) {
+    return [
+        a[0] * b[0] + a[2] * b[1],
+        a[1] * b[0] + a[3] * b[1],
+        a[0] * b[2] + a[2] * b[3],
+        a[1] * b[2] + a[3] * b[3],
+        a[0] * b[4] + a[2] * b[5] + a[4],
+        a[1] * b[4] + a[3] * b[5] + a[5],
+    ];
+}
+function applyM(m, x, y) {
+    return [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]];
+}
+/**
+ * Extract all checked checkbox positions from a given PDF page.
+ *
+ * @returns Array of {x, y} positions where a checkbox is checked,
+ *          in the same coordinate space as extracted TextLine objects.
+ */
+export async function extractCheckedBoxes(buffer, pageNum) {
+    const uint8 = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    const pdf = await getDocument({ data: uint8, useSystemFonts: true }).promise;
+    const page = await pdf.getPage(pageNum);
+    const viewport = page.getViewport({ scale: 1 });
+    const pageHeight = viewport.height;
+    const ops = await page.getOperatorList();
+    const opsNames = {};
+    for (const [name, val] of Object.entries(OPS)) {
+        opsNames[val] = name;
+    }
+    // Track current transformation matrix with save/restore stack
+    let ctm = [1, 0, 0, 1, 0, 0];
+    const stack = [];
+    // Collect all small (~8×8 pt) path shapes and their page coordinates
+    const shapes = [];
+    for (let i = 0; i < ops.fnArray.length; i++) {
+        const fn = ops.fnArray[i];
+        const args = ops.argsArray[i];
+        const name = opsNames[fn];
+        if (name === "save") {
+            stack.push([...ctm]);
+            continue;
+        }
+        if (name === "restore") {
+            ctm = stack.pop() ?? [1, 0, 0, 1, 0, 0];
+            continue;
+        }
+        if (name === "transform") {
+            ctm = multiply(ctm, args);
+            continue;
+        }
+        if (name === "constructPath") {
+            const [opcodes, pathArgs] = args;
+            let ai = 0;
+            const points = [];
+            for (const op of opcodes) {
+                if (op === 13 /* moveTo */ || op === 14 /* lineTo */) {
+                    const px = pathArgs[ai++];
+                    const py = pathArgs[ai++];
+                    points.push(applyM(ctm, px, py));
+                }
+                else if (op === 19 /* rectangle */) {
+                    const rx = pathArgs[ai++], ry = pathArgs[ai++];
+                    const rw = pathArgs[ai++], rh = pathArgs[ai++];
+                    points.push(applyM(ctm, rx, ry));
+                    points.push(applyM(ctm, rx + rw, ry + rh));
+                }
+                else if (op === 18 /* closePath */) {
+                    // no args
+                }
+            }
+            if (points.length >= 2) {
+                const xs = points.map((p) => p[0]);
+                const ys = points.map((p) => p[1]);
+                const minX = Math.min(...xs);
+                const maxX = Math.max(...xs);
+                const minY = Math.min(...ys);
+                const maxY = Math.max(...ys);
+                const w = maxX - minX;
+                const h = maxY - minY;
+                // Checkbox squares are ~8.4×8.4 pt; allow 6-11 range
+                if (w >= 6 && w <= 11 && h >= 6 && h <= 11) {
+                    // Convert from PDF bottom-up to top-down text coordinates
+                    const textY = pageHeight - maxY;
+                    shapes.push({ x: Math.round(minX * 10) / 10, y: Math.round(textY * 10) / 10 });
+                }
+            }
+        }
+    }
+    // Group shapes by position (within 3pt tolerance)
+    const groups = new Map();
+    for (const s of shapes) {
+        // Round to nearest 2pt grid to group nearby shapes
+        const key = `${Math.round(s.x / 2) * 2},${Math.round(s.y / 2) * 2}`;
+        groups.set(key, (groups.get(key) ?? 0) + 1);
+    }
+    // Checked checkboxes have >= 3 shapes at the same position
+    const checked = [];
+    for (const [key, count] of groups) {
+        if (count >= 3) {
+            const [x, y] = key.split(",").map(Number);
+            checked.push({ x, y });
+        }
+    }
+    return checked;
+}
+/**
+ * Given a list of checked positions and a set of checkbox options
+ * at known x-positions on a given text-y row, return which option is checked.
+ *
+ * The checkbox square is rendered ~7pt above the text label (lower y value
+ * in top-down coordinates) and ~12pt to its left. Since rows are only
+ * ~11pt apart, we use a directional y-match: the checkbox must be above
+ * the text line (yDiff in [2, 12]) to avoid cross-row false positives.
+ *
+ * @param checked - Array of checked checkbox positions
+ * @param textY - The y-coordinate of the text row (from TextLine.y)
+ * @param options - Map of checkbox x-position to option label
+ * @param xTolerance - x-axis matching tolerance in points (default 6)
+ */
+export function resolveCheckbox(checked, textY, options, xTolerance = 6) {
+    for (const opt of options) {
+        // The checkbox square sits ~12pt to the left of the label text
+        const checkboxX = opt.x - 12.3;
+        const match = checked.find((c) => {
+            const yDiff = textY - c.y; // positive when checkbox is above text
+            return Math.abs(c.x - checkboxX) < xTolerance && yDiff >= 2 && yDiff <= 12;
+        });
+        if (match)
+            return opt.label;
+    }
+    return "";
+}

package/dist/form-1004mc/index.d.ts

@@ -0,0 +1,3 @@
+export { parseForm1004MC, parseForm1004MCFromLines } from "./parser.js";
+export type { Form1004MCReport, SubjectSection, ContractSection, NeighborhoodSection, SiteSection, ImprovementsSection, ComparableSale, SalesComparisonSection, ReconciliationSection, CostApproachSection, MarketConditionsAddendum, Form1004MCHeader, InventoryAnalysis, MedianSaleListData, MarketAnalysisText, CondoCoopProjects, AppraiserInfo, TimePeriodRow, Trend, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/form-1004mc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/form-1004mc/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC"}

package/dist/form-1004mc/index.js

@@ -0,0 +1 @@
+export { parseForm1004MC, parseForm1004MCFromLines } from "./parser.js";

package/dist/form-1004mc/parse-page1.d.ts

@@ -0,0 +1,8 @@
+import type { TextLine } from "@parseo/shared";
+import type { SubjectSection, ContractSection, NeighborhoodSection, SiteSection, ImprovementsSection } from "./types.js";
+export declare function parseSubjectSection(lines: TextLine[]): SubjectSection;
+export declare function parseContractSection(lines: TextLine[]): ContractSection;
+export declare function parseNeighborhoodSection(lines: TextLine[]): NeighborhoodSection;
+export declare function parseSiteSection(lines: TextLine[]): SiteSection;
+export declare function parseImprovementsSection(lines: TextLine[]): ImprovementsSection;
+//# sourceMappingURL=parse-page1.d.ts.map

package/dist/form-1004mc/parse-page1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-page1.d.ts","sourceRoot":"","sources":["../../src/form-1004mc/parse-page1.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAiDpB,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,cAAc,CAuGrE;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,eAAe,CA6CvE;AAID,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CA0I/E;AAID,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,WAAW,CAkE/D;AAID,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CAgN/E"}