floorplan-diff

Node library for comparing two floor plan PDF buffers and returning differences as normalized points and regions.

Installation

npm install floorplan-diff

Runtime requirements

• Node.js >=20.16.
• In Node environments, install @napi-rs/canvas in the host app to ensure PDF rendering compatibility:

npm install @napi-rs/canvas

Usage

import { compareFloorPlans } from 'floorplan-diff';

const result = await compareFloorPlans({
  baseBuffer,
  compareBuffer,
  options: {
    includeRegions: true,
    includePoints: true,
  },
});

For CommonJS hosts:

const { compareFloorPlans } = require('floorplan-diff');

Input format

• PDF buffers only.
• If a different format is provided, the library throws UNSUPPORTED_BUFFER_FORMAT.

Result

{
  points: [
    { x: 0.52, y: 0.31 }
  ],
  regions: [
    { x: 0.5, y: 0.25, width: 0.1, height: 0.12, cx: 0.55, cy: 0.31 }
  ],
  summary: {
    changedPixels: 512,
    totalPixels: 102400,
    changePercent: 0.5,
    pointsCount: 1,
    regionsCount: 1
  }
}

API

• compareFloorPlans({ baseBuffer, compareBuffer, options })
• isPdfBuffer(buffer)
• convertFirstPagePdfToPng(pdfBuffer, scale?)

Errors

The library throws PlanDiffError with this structure:

{
  name: 'PlanDiffError',
  code: 'PDF_PAGE_SIZE_MISMATCH',
  message: 'Cannot compare PDFs with different page sizes',
  details: { ... }
}

Main error codes:

• INVALID_BUFFER
• UNSUPPORTED_BUFFER_FORMAT
• PDF_PARSE_ERROR
• PDF_PAGE_SIZE_MISMATCH
• PDF_PAGE_ORIENTATION_MISMATCH
• IMAGE_DECODE_ERROR
• INTERNAL_PROCESSING_ERROR

Notes

• Coordinates are normalized to the [0, 1] range.
• If no changes are detected, the library returns empty arrays.
• npm run build generates both ESM output (dist/index.js) and a CJS-compatible entrypoint (dist/index.cjs) used by exports.require.