skew-score 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay Misal (vjymisal0)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# skew-score
+
+> Quantifies document and image tilt/skew angle (-45° to +45°) using Radon projection profile variance analysis via Sharp. Optimized for pre-OCR document scanning, KYC ID verification, and receipt processing.
+
+[![npm version](https://img.shields.io/npm/v/skew-score.svg)](https://www.npmjs.com/package/skew-score)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Why skew-score?
+
+When users photograph identification cards (PAN, Aadhaar, Driver Licenses), checks, or receipts with mobile cameras, angular tilt and perspective skew degrade OCR accuracy by up to 60%.
+
+`skew-score` runs an ultra-fast angular sweep across directional edge projections to accurately compute:
+- **Exact tilt angle** (-45.0° to +45.0°)
+- **Corrective rotation** required to straighten the image
+- **Skew severity score** (0.0 = aligned, 1.0 = heavily tilted)
+
+Companion to [`blur-score`](https://www.npmjs.com/package/blur-score), [`exposure-score`](https://www.npmjs.com/package/exposure-score), [`glare-score`](https://www.npmjs.com/package/glare-score), and [`contrast-score`](https://www.npmjs.com/package/contrast-score).
+
+## Installation
+
+```bash
+npm install skew-score sharp
+# or
+pnpm add skew-score sharp
+```
+
+## Usage
+
+### 1. Analyze Skew
+
+```typescript
+import { analyzeSkew } from 'skew-score';
+
+const result = await analyzeSkew('path/to/document.jpg');
+console.log(result);
+/*
+{
+  angle: -8.5,
+  score: 0.1889,
+  isSkewed: true,
+  confidence: 0.84,
+  correctiveRotation: 8.5,
+  quality: 'moderate-skew',
+  details: {
+    angle: -8.5,
+    confidence: 0.84,
+    width: 400,
+    height: 260
+  }
+}
+*/
+```
+
+### 2. Quick Helpers
+
+```typescript
+import { getSkewAngle, isSkewed } from 'skew-score';
+
+// Get just the rotation angle
+const angle = await getSkewAngle(buffer); // e.g. -4.2
+
+// Check if tilted beyond threshold (default 3 degrees)
+if (await isSkewed(buffer)) {
+  console.log('Please hold the camera level with your document.');
+}
+```
+
+### 3. Straightening the Document
+
+```typescript
+import sharp from 'sharp';
+import { analyzeSkew } from 'skew-score';
+
+const result = await analyzeSkew(imageBuffer);
+if (result.isSkewed && result.confidence > 0.5) {
+  const deskewedBuffer = await sharp(imageBuffer)
+    .rotate(result.correctiveRotation, { background: '#ffffff' })
+    .toBuffer();
+}
+```
+
+## Options
+
+```typescript
+interface SkewOptions {
+  /** Maximum allowed tilt before flagging as skewed (default: 3.0 degrees) */
+  angleThreshold?: number;
+  /** Minimum confidence required to accept angle (default: 0.20) */
+  minConfidence?: number;
+  /** Maximum angle search range (default: 45) */
+  maxAngle?: number;
+  /** Angular search step resolution (default: 0.5 degrees) */
+  angleStep?: number;
+  /** Downsample width for fast processing (default: 400px) */
+  downsampleWidth?: number;
+}
+```
+
+## License
+
+MIT © [Vijay Misal](https://github.com/vjymisal0)

package/dist/index.cjs

@@ -0,0 +1,144 @@
+'use strict';
+
+var sharp = require('sharp');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var sharp__default = /*#__PURE__*/_interopDefault(sharp);
+
+// src/detector.ts
+function normalizeOptions(options) {
+  return {
+    angleThreshold: options?.angleThreshold ?? 3,
+    minConfidence: options?.minConfidence ?? 0.2,
+    maxAngle: options?.maxAngle ?? 45,
+    angleStep: options?.angleStep ?? 0.5,
+    downsampleWidth: options?.downsampleWidth ?? 400
+  };
+}
+function evaluateProjectionVariance(edgeMap, width, height, angleDegrees) {
+  const rad = angleDegrees * Math.PI / 180;
+  const sin = Math.sin(rad);
+  const cos = Math.cos(rad);
+  const cx = width / 2;
+  const cy = height / 2;
+  const projectedRows = new Float64Array(height);
+  const countPerBin = new Int32Array(height);
+  for (let y = 0; y < height; y++) {
+    const dy = y - cy;
+    const rowOffset = y * width;
+    for (let x = 0; x < width; x++) {
+      const val = edgeMap[rowOffset + x];
+      if (val === 0) continue;
+      const dx = x - cx;
+      const rotY = Math.round(-dx * sin + dy * cos + cy);
+      if (rotY >= 0 && rotY < height) {
+        projectedRows[rotY] += val;
+        countPerBin[rotY] += 1;
+      }
+    }
+  }
+  let sum = 0;
+  let sumSq = 0;
+  let count = 0;
+  for (let i = 0; i < height; i++) {
+    if (countPerBin[i] > 0) {
+      const val = projectedRows[i];
+      sum += val;
+      sumSq += val * val;
+      count++;
+    }
+  }
+  if (count <= 1) return 0;
+  const mean = sum / count;
+  return sumSq / count - mean * mean;
+}
+async function analyzeSkew(input, options) {
+  const opts = normalizeOptions(options);
+  const { data: rawGray, info } = await sharp__default.default(input).resize({ width: opts.downsampleWidth, withoutEnlargement: true }).grayscale().raw().toBuffer({ resolveWithObject: true });
+  const width = info.width;
+  const height = info.height;
+  const totalPixels = width * height;
+  if (totalPixels === 0) {
+    throw new Error("Image contains no pixel data.");
+  }
+  const edges = new Uint8Array(totalPixels);
+  for (let y = 1; y < height - 1; y++) {
+    const rPrev = (y - 1) * width;
+    const rCurr = y * width;
+    const rNext = (y + 1) * width;
+    for (let x = 1; x < width - 1; x++) {
+      const gy = -(rawGray[rPrev + x - 1] + 2 * rawGray[rPrev + x] + rawGray[rPrev + x + 1]) + (rawGray[rNext + x - 1] + 2 * rawGray[rNext + x] + rawGray[rNext + x + 1]);
+      const mag = Math.abs(gy);
+      edges[rCurr + x] = mag > 45 ? 255 : 0;
+    }
+  }
+  let bestAngle = 0;
+  let maxVariance = -1;
+  let minVariance = Infinity;
+  const startAngle = -opts.maxAngle;
+  const endAngle = opts.maxAngle;
+  const step = opts.angleStep;
+  for (let angle = startAngle; angle <= endAngle; angle += step) {
+    const roundedAngle = Math.round(angle * 100) / 100;
+    const variance = evaluateProjectionVariance(edges, width, height, roundedAngle);
+    if (variance > maxVariance) {
+      maxVariance = variance;
+      bestAngle = roundedAngle;
+    }
+    if (variance < minVariance) {
+      minVariance = variance;
+    }
+  }
+  const baseline = minVariance === Infinity || minVariance < 0 ? 0 : minVariance;
+  const peakContrast = maxVariance > baseline && baseline > 0 ? (maxVariance - baseline) / maxVariance : 0;
+  const confidence = Number(Math.min(1, Math.max(0, peakContrast)).toFixed(3));
+  const finalAngle = confidence >= opts.minConfidence ? bestAngle : 0;
+  const absAngle = Math.abs(finalAngle);
+  const score = Number(Math.min(1, absAngle / 45).toFixed(4));
+  const isSkewed2 = absAngle >= opts.angleThreshold;
+  const correctiveRotation = finalAngle === 0 ? 0 : Number((-finalAngle).toFixed(2));
+  let quality;
+  if (absAngle < 1) {
+    quality = "straight";
+  } else if (absAngle <= opts.angleThreshold) {
+    quality = "slight-tilt";
+  } else if (absAngle <= 15) {
+    quality = "moderate-skew";
+  } else {
+    quality = "severe-skew";
+  }
+  const details = {
+    angle: finalAngle,
+    confidence,
+    width,
+    height
+  };
+  return {
+    angle: finalAngle,
+    score,
+    isSkewed: isSkewed2,
+    confidence,
+    correctiveRotation,
+    quality,
+    details
+  };
+}
+async function getSkewAngle(input, options) {
+  const res = await analyzeSkew(input, options);
+  return res.angle;
+}
+async function isSkewed(input, threshold) {
+  const options = {};
+  if (threshold !== void 0) {
+    options.angleThreshold = threshold;
+  }
+  const res = await analyzeSkew(input, options);
+  return res.isSkewed;
+}
+
+exports.analyzeSkew = analyzeSkew;
+exports.getSkewAngle = getSkewAngle;
+exports.isSkewed = isSkewed;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/detector.ts"],"names":["sharp","isSkewed"],"mappings":"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","file":"index.cjs","sourcesContent":["import sharp from 'sharp';\r\nimport type { SkewOptions, SkewResult, SkewDetails } from './types.js';\r\n\r\nexport function normalizeOptions(options?: SkewOptions): Required<SkewOptions> {\r\n  return {\r\n    angleThreshold: options?.angleThreshold ?? 3.0,\r\n    minConfidence: options?.minConfidence ?? 0.20,\r\n    maxAngle: options?.maxAngle ?? 45,\r\n    angleStep: options?.angleStep ?? 0.5,\r\n    downsampleWidth: options?.downsampleWidth ?? 400\r\n  };\r\n}\r\n\r\n/**\r\n * Computes horizontal projection profile variance at a specific rotation angle.\r\n * When text lines or document edges are aligned horizontally, the variance of row sums is maximized.\r\n */\r\nfunction evaluateProjectionVariance(\r\n  edgeMap: Uint8Array,\r\n  width: number,\r\n  height: number,\r\n  angleDegrees: number\r\n): number {\r\n  const rad = (angleDegrees * Math.PI) / 180;\r\n  const sin = Math.sin(rad);\r\n  const cos = Math.cos(rad);\r\n\r\n  const cx = width / 2;\r\n  const cy = height / 2;\r\n\r\n  // Project onto vertical axis (row projection)\r\n  // Bounded buffer for projected row sums\r\n  const projectedRows = new Float64Array(height);\r\n  const countPerBin = new Int32Array(height);\r\n\r\n  for (let y = 0; y < height; y++) {\r\n    const dy = y - cy;\r\n    const rowOffset = y * width;\r\n    for (let x = 0; x < width; x++) {\r\n      const val = edgeMap[rowOffset + x]!;\r\n      if (val === 0) continue;\r\n\r\n      const dx = x - cx;\r\n      // Rotated Y coordinate: -dx * sin + dy * cos + cy\r\n      const rotY = Math.round(-dx * sin + dy * cos + cy);\r\n\r\n      if (rotY >= 0 && rotY < height) {\r\n        projectedRows[rotY] += val;\r\n        countPerBin[rotY] += 1;\r\n      }\r\n    }\r\n  }\r\n\r\n  // Calculate variance of non-empty bins\r\n  let sum = 0;\r\n  let sumSq = 0;\r\n  let count = 0;\r\n\r\n  for (let i = 0; i < height; i++) {\r\n    if (countPerBin[i]! > 0) {\r\n      const val = projectedRows[i]!;\r\n      sum += val;\r\n      sumSq += val * val;\r\n      count++;\r\n    }\r\n  }\r\n\r\n  if (count <= 1) return 0;\r\n  const mean = sum / count;\r\n  return (sumSq / count) - (mean * mean);\r\n}\r\n\r\n/**\r\n * Analyzes document and text skew using Radon / Horizontal Projection Profile variance.\r\n *\r\n * @param input - File path, Buffer, or Uint8Array representing an image.\r\n * @param options - Configurable parameters.\r\n * @returns Promise resolving to a SkewResult.\r\n */\r\nexport async function analyzeSkew(\r\n  input: string | Buffer | Uint8Array,\r\n  options?: SkewOptions\r\n): Promise<SkewResult> {\r\n  const opts = normalizeOptions(options);\r\n\r\n  // Load image, grayscale, downsample\r\n  const { data: rawGray, info } = await sharp(input)\r\n    .resize({ width: opts.downsampleWidth, withoutEnlargement: true })\r\n    .grayscale()\r\n    .raw()\r\n    .toBuffer({ resolveWithObject: true });\r\n\r\n  const width = info.width;\r\n  const height = info.height;\r\n  const totalPixels = width * height;\r\n\r\n  if (totalPixels === 0) {\r\n    throw new Error('Image contains no pixel data.');\r\n  }\r\n\r\n  // Fast Sobel horizontal edge filtering (horizontal edges are most sensitive to tilt)\r\n  const edges = new Uint8Array(totalPixels);\r\n  for (let y = 1; y < height - 1; y++) {\r\n    const rPrev = (y - 1) * width;\r\n    const rCurr = y * width;\r\n    const rNext = (y + 1) * width;\r\n\r\n    for (let x = 1; x < width - 1; x++) {\r\n      // Sobel Y (horizontal gradients)\r\n      const gy =\r\n        -(rawGray[rPrev + x - 1]! + 2 * rawGray[rPrev + x]! + rawGray[rPrev + x + 1]!) +\r\n        (rawGray[rNext + x - 1]! + 2 * rawGray[rNext + x]! + rawGray[rNext + x + 1]!);\r\n\r\n      const mag = Math.abs(gy);\r\n      // Threshold edges to binary structure\r\n      edges[rCurr + x] = mag > 45 ? 255 : 0;\r\n    }\r\n  }\r\n\r\n  // Angular sweep to find peak variance\r\n  let bestAngle = 0;\r\n  let maxVariance = -1;\r\n  let minVariance = Infinity;\r\n  let zeroAngleVariance = 0;\r\n\r\n  const startAngle = -opts.maxAngle;\r\n  const endAngle = opts.maxAngle;\r\n  const step = opts.angleStep;\r\n\r\n  const variances: { angle: number; variance: number }[] = [];\r\n\r\n  for (let angle = startAngle; angle <= endAngle; angle += step) {\r\n    const roundedAngle = Math.round(angle * 100) / 100;\r\n    const variance = evaluateProjectionVariance(edges, width, height, roundedAngle);\r\n\r\n    variances.push({ angle: roundedAngle, variance });\r\n\r\n    if (roundedAngle === 0) {\r\n      zeroAngleVariance = variance;\r\n    }\r\n\r\n    if (variance > maxVariance) {\r\n      maxVariance = variance;\r\n      bestAngle = roundedAngle;\r\n    }\r\n    if (variance < minVariance) {\r\n      minVariance = variance;\r\n    }\r\n  }\r\n\r\n  // Compute confidence based on contrast between peak variance and baseline variance\r\n  const baseline = (minVariance === Infinity || minVariance < 0) ? 0 : minVariance;\r\n  const peakContrast = maxVariance > baseline && baseline > 0\r\n    ? (maxVariance - baseline) / maxVariance\r\n    : 0;\r\n\r\n  const confidence = Number(Math.min(1.0, Math.max(0.0, peakContrast)).toFixed(3));\r\n\r\n  // If confidence is too low (e.g. blank page or uniform texture), assume 0 skew\r\n  const finalAngle = confidence >= opts.minConfidence ? bestAngle : 0;\r\n  const absAngle = Math.abs(finalAngle);\r\n\r\n  // Normalized score (0.0 = 0 deg, 1.0 = 45+ deg)\r\n  const score = Number(Math.min(1.0, absAngle / 45).toFixed(4));\r\n  const isSkewed = absAngle >= opts.angleThreshold;\r\n\r\n  // Corrective rotation is opposite of detected angle\r\n  const correctiveRotation = finalAngle === 0 ? 0 : Number((-finalAngle).toFixed(2));\r\n\r\n  let quality: 'straight' | 'slight-tilt' | 'moderate-skew' | 'severe-skew';\r\n  if (absAngle < 1.0) {\r\n    quality = 'straight';\r\n  } else if (absAngle <= opts.angleThreshold) {\r\n    quality = 'slight-tilt';\r\n  } else if (absAngle <= 15.0) {\r\n    quality = 'moderate-skew';\r\n  } else {\r\n    quality = 'severe-skew';\r\n  }\r\n\r\n  const details: SkewDetails = {\r\n    angle: finalAngle,\r\n    confidence,\r\n    width,\r\n    height\r\n  };\r\n\r\n  return {\r\n    angle: finalAngle,\r\n    score,\r\n    isSkewed,\r\n    confidence,\r\n    correctiveRotation,\r\n    quality,\r\n    details\r\n  };\r\n}\r\n\r\n/**\r\n * Returns only the detected skew angle in degrees.\r\n */\r\nexport async function getSkewAngle(\r\n  input: string | Buffer | Uint8Array,\r\n  options?: SkewOptions\r\n): Promise<number> {\r\n  const res = await analyzeSkew(input, options);\r\n  return res.angle;\r\n}\r\n\r\n/**\r\n * Returns true if the image exceeds the skew threshold.\r\n */\r\nexport async function isSkewed(\r\n  input: string | Buffer | Uint8Array,\r\n  threshold?: number\r\n): Promise<boolean> {\r\n  const options: SkewOptions = {};\r\n  if (threshold !== undefined) {\r\n    options.angleThreshold = threshold;\r\n  }\r\n  const res = await analyzeSkew(input, options);\r\n  return res.isSkewed;\r\n}\r\n"]}

package/dist/index.d.cts

@@ -0,0 +1,94 @@
+interface SkewDetails {
+    /**
+     * Detected skew angle in degrees (negative = counter-clockwise, positive = clockwise).
+     */
+    angle: number;
+    /**
+     * Confidence of the detected angle from 0.0 to 1.0.
+     */
+    confidence: number;
+    /**
+     * Width of the analyzed image after optional downsampling.
+     */
+    width: number;
+    /**
+     * Height of the analyzed image after optional downsampling.
+     */
+    height: number;
+}
+interface SkewOptions {
+    /**
+     * Maximum allowed absolute tilt angle in degrees before flagging as skewed.
+     * @default 3.0
+     */
+    angleThreshold?: number;
+    /**
+     * Minimum confidence score (0.0 to 1.0) required to consider skew detection valid.
+     * @default 0.25
+     */
+    minConfidence?: number;
+    /**
+     * Search range of angles to inspect in degrees [-range, +range].
+     * @default 45
+     */
+    maxAngle?: number;
+    /**
+     * Step size in degrees during angular projection search.
+     * @default 0.5
+     */
+    angleStep?: number;
+    /**
+     * Target width to resize the image for blazing fast analysis.
+     * @default 400
+     */
+    downsampleWidth?: number;
+}
+interface SkewResult {
+    /**
+     * Detected skew angle in degrees (-45° to +45°).
+     */
+    angle: number;
+    /**
+     * Normalized skew severity score from 0.0 (perfectly straight) to 1.0 (heavily rotated).
+     */
+    score: number;
+    /**
+     * True if absolute angle exceeds angleThreshold.
+     */
+    isSkewed: boolean;
+    /**
+     * Confidence level of detection (0.0 to 1.0).
+     */
+    confidence: number;
+    /**
+     * Suggested rotation angle (in degrees) needed to de-skew / straighten the image.
+     */
+    correctiveRotation: number;
+    /**
+     * Qualitative alignment rating.
+     */
+    quality: 'straight' | 'slight-tilt' | 'moderate-skew' | 'severe-skew';
+    /**
+     * Optional granular diagnostics.
+     */
+    details?: SkewDetails;
+}
+
+/**
+ * Analyzes document and text skew using Radon / Horizontal Projection Profile variance.
+ *
+ * @param input - File path, Buffer, or Uint8Array representing an image.
+ * @param options - Configurable parameters.
+ * @returns Promise resolving to a SkewResult.
+ */
+declare function analyzeSkew(input: string | Buffer | Uint8Array, options?: SkewOptions): Promise<SkewResult>;
+/**
+ * Returns only the detected skew angle in degrees.
+ */
+declare function getSkewAngle(input: string | Buffer | Uint8Array, options?: SkewOptions): Promise<number>;
+/**
+ * Returns true if the image exceeds the skew threshold.
+ */
+declare function isSkewed(input: string | Buffer | Uint8Array, threshold?: number): Promise<boolean>;
+
+export { type SkewDetails, type SkewOptions, type SkewResult, analyzeSkew, getSkewAngle, isSkewed };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+interface SkewDetails {
+    /**
+     * Detected skew angle in degrees (negative = counter-clockwise, positive = clockwise).
+     */
+    angle: number;
+    /**
+     * Confidence of the detected angle from 0.0 to 1.0.
+     */
+    confidence: number;
+    /**
+     * Width of the analyzed image after optional downsampling.
+     */
+    width: number;
+    /**
+     * Height of the analyzed image after optional downsampling.
+     */
+    height: number;
+}
+interface SkewOptions {
+    /**
+     * Maximum allowed absolute tilt angle in degrees before flagging as skewed.
+     * @default 3.0
+     */
+    angleThreshold?: number;
+    /**
+     * Minimum confidence score (0.0 to 1.0) required to consider skew detection valid.
+     * @default 0.25
+     */
+    minConfidence?: number;
+    /**
+     * Search range of angles to inspect in degrees [-range, +range].
+     * @default 45
+     */
+    maxAngle?: number;
+    /**
+     * Step size in degrees during angular projection search.
+     * @default 0.5
+     */
+    angleStep?: number;
+    /**
+     * Target width to resize the image for blazing fast analysis.
+     * @default 400
+     */
+    downsampleWidth?: number;
+}
+interface SkewResult {
+    /**
+     * Detected skew angle in degrees (-45° to +45°).
+     */
+    angle: number;
+    /**
+     * Normalized skew severity score from 0.0 (perfectly straight) to 1.0 (heavily rotated).
+     */
+    score: number;
+    /**
+     * True if absolute angle exceeds angleThreshold.
+     */
+    isSkewed: boolean;
+    /**
+     * Confidence level of detection (0.0 to 1.0).
+     */
+    confidence: number;
+    /**
+     * Suggested rotation angle (in degrees) needed to de-skew / straighten the image.
+     */
+    correctiveRotation: number;
+    /**
+     * Qualitative alignment rating.
+     */
+    quality: 'straight' | 'slight-tilt' | 'moderate-skew' | 'severe-skew';
+    /**
+     * Optional granular diagnostics.
+     */
+    details?: SkewDetails;
+}
+
+/**
+ * Analyzes document and text skew using Radon / Horizontal Projection Profile variance.
+ *
+ * @param input - File path, Buffer, or Uint8Array representing an image.
+ * @param options - Configurable parameters.
+ * @returns Promise resolving to a SkewResult.
+ */
+declare function analyzeSkew(input: string | Buffer | Uint8Array, options?: SkewOptions): Promise<SkewResult>;
+/**
+ * Returns only the detected skew angle in degrees.
+ */
+declare function getSkewAngle(input: string | Buffer | Uint8Array, options?: SkewOptions): Promise<number>;
+/**
+ * Returns true if the image exceeds the skew threshold.
+ */
+declare function isSkewed(input: string | Buffer | Uint8Array, threshold?: number): Promise<boolean>;
+
+export { type SkewDetails, type SkewOptions, type SkewResult, analyzeSkew, getSkewAngle, isSkewed };

package/dist/index.js

@@ -0,0 +1,136 @@
+import sharp from 'sharp';
+
+// src/detector.ts
+function normalizeOptions(options) {
+  return {
+    angleThreshold: options?.angleThreshold ?? 3,
+    minConfidence: options?.minConfidence ?? 0.2,
+    maxAngle: options?.maxAngle ?? 45,
+    angleStep: options?.angleStep ?? 0.5,
+    downsampleWidth: options?.downsampleWidth ?? 400
+  };
+}
+function evaluateProjectionVariance(edgeMap, width, height, angleDegrees) {
+  const rad = angleDegrees * Math.PI / 180;
+  const sin = Math.sin(rad);
+  const cos = Math.cos(rad);
+  const cx = width / 2;
+  const cy = height / 2;
+  const projectedRows = new Float64Array(height);
+  const countPerBin = new Int32Array(height);
+  for (let y = 0; y < height; y++) {
+    const dy = y - cy;
+    const rowOffset = y * width;
+    for (let x = 0; x < width; x++) {
+      const val = edgeMap[rowOffset + x];
+      if (val === 0) continue;
+      const dx = x - cx;
+      const rotY = Math.round(-dx * sin + dy * cos + cy);
+      if (rotY >= 0 && rotY < height) {
+        projectedRows[rotY] += val;
+        countPerBin[rotY] += 1;
+      }
+    }
+  }
+  let sum = 0;
+  let sumSq = 0;
+  let count = 0;
+  for (let i = 0; i < height; i++) {
+    if (countPerBin[i] > 0) {
+      const val = projectedRows[i];
+      sum += val;
+      sumSq += val * val;
+      count++;
+    }
+  }
+  if (count <= 1) return 0;
+  const mean = sum / count;
+  return sumSq / count - mean * mean;
+}
+async function analyzeSkew(input, options) {
+  const opts = normalizeOptions(options);
+  const { data: rawGray, info } = await sharp(input).resize({ width: opts.downsampleWidth, withoutEnlargement: true }).grayscale().raw().toBuffer({ resolveWithObject: true });
+  const width = info.width;
+  const height = info.height;
+  const totalPixels = width * height;
+  if (totalPixels === 0) {
+    throw new Error("Image contains no pixel data.");
+  }
+  const edges = new Uint8Array(totalPixels);
+  for (let y = 1; y < height - 1; y++) {
+    const rPrev = (y - 1) * width;
+    const rCurr = y * width;
+    const rNext = (y + 1) * width;
+    for (let x = 1; x < width - 1; x++) {
+      const gy = -(rawGray[rPrev + x - 1] + 2 * rawGray[rPrev + x] + rawGray[rPrev + x + 1]) + (rawGray[rNext + x - 1] + 2 * rawGray[rNext + x] + rawGray[rNext + x + 1]);
+      const mag = Math.abs(gy);
+      edges[rCurr + x] = mag > 45 ? 255 : 0;
+    }
+  }
+  let bestAngle = 0;
+  let maxVariance = -1;
+  let minVariance = Infinity;
+  const startAngle = -opts.maxAngle;
+  const endAngle = opts.maxAngle;
+  const step = opts.angleStep;
+  for (let angle = startAngle; angle <= endAngle; angle += step) {
+    const roundedAngle = Math.round(angle * 100) / 100;
+    const variance = evaluateProjectionVariance(edges, width, height, roundedAngle);
+    if (variance > maxVariance) {
+      maxVariance = variance;
+      bestAngle = roundedAngle;
+    }
+    if (variance < minVariance) {
+      minVariance = variance;
+    }
+  }
+  const baseline = minVariance === Infinity || minVariance < 0 ? 0 : minVariance;
+  const peakContrast = maxVariance > baseline && baseline > 0 ? (maxVariance - baseline) / maxVariance : 0;
+  const confidence = Number(Math.min(1, Math.max(0, peakContrast)).toFixed(3));
+  const finalAngle = confidence >= opts.minConfidence ? bestAngle : 0;
+  const absAngle = Math.abs(finalAngle);
+  const score = Number(Math.min(1, absAngle / 45).toFixed(4));
+  const isSkewed2 = absAngle >= opts.angleThreshold;
+  const correctiveRotation = finalAngle === 0 ? 0 : Number((-finalAngle).toFixed(2));
+  let quality;
+  if (absAngle < 1) {
+    quality = "straight";
+  } else if (absAngle <= opts.angleThreshold) {
+    quality = "slight-tilt";
+  } else if (absAngle <= 15) {
+    quality = "moderate-skew";
+  } else {
+    quality = "severe-skew";
+  }
+  const details = {
+    angle: finalAngle,
+    confidence,
+    width,
+    height
+  };
+  return {
+    angle: finalAngle,
+    score,
+    isSkewed: isSkewed2,
+    confidence,
+    correctiveRotation,
+    quality,
+    details
+  };
+}
+async function getSkewAngle(input, options) {
+  const res = await analyzeSkew(input, options);
+  return res.angle;
+}
+async function isSkewed(input, threshold) {
+  const options = {};
+  if (threshold !== void 0) {
+    options.angleThreshold = threshold;
+  }
+  const res = await analyzeSkew(input, options);
+  return res.isSkewed;
+}
+
+export { analyzeSkew, getSkewAngle, isSkewed };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/detector.ts"],"names":["isSkewed"],"mappings":"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","file":"index.js","sourcesContent":["import sharp from 'sharp';\r\nimport type { SkewOptions, SkewResult, SkewDetails } from './types.js';\r\n\r\nexport function normalizeOptions(options?: SkewOptions): Required<SkewOptions> {\r\n  return {\r\n    angleThreshold: options?.angleThreshold ?? 3.0,\r\n    minConfidence: options?.minConfidence ?? 0.20,\r\n    maxAngle: options?.maxAngle ?? 45,\r\n    angleStep: options?.angleStep ?? 0.5,\r\n    downsampleWidth: options?.downsampleWidth ?? 400\r\n  };\r\n}\r\n\r\n/**\r\n * Computes horizontal projection profile variance at a specific rotation angle.\r\n * When text lines or document edges are aligned horizontally, the variance of row sums is maximized.\r\n */\r\nfunction evaluateProjectionVariance(\r\n  edgeMap: Uint8Array,\r\n  width: number,\r\n  height: number,\r\n  angleDegrees: number\r\n): number {\r\n  const rad = (angleDegrees * Math.PI) / 180;\r\n  const sin = Math.sin(rad);\r\n  const cos = Math.cos(rad);\r\n\r\n  const cx = width / 2;\r\n  const cy = height / 2;\r\n\r\n  // Project onto vertical axis (row projection)\r\n  // Bounded buffer for projected row sums\r\n  const projectedRows = new Float64Array(height);\r\n  const countPerBin = new Int32Array(height);\r\n\r\n  for (let y = 0; y < height; y++) {\r\n    const dy = y - cy;\r\n    const rowOffset = y * width;\r\n    for (let x = 0; x < width; x++) {\r\n      const val = edgeMap[rowOffset + x]!;\r\n      if (val === 0) continue;\r\n\r\n      const dx = x - cx;\r\n      // Rotated Y coordinate: -dx * sin + dy * cos + cy\r\n      const rotY = Math.round(-dx * sin + dy * cos + cy);\r\n\r\n      if (rotY >= 0 && rotY < height) {\r\n        projectedRows[rotY] += val;\r\n        countPerBin[rotY] += 1;\r\n      }\r\n    }\r\n  }\r\n\r\n  // Calculate variance of non-empty bins\r\n  let sum = 0;\r\n  let sumSq = 0;\r\n  let count = 0;\r\n\r\n  for (let i = 0; i < height; i++) {\r\n    if (countPerBin[i]! > 0) {\r\n      const val = projectedRows[i]!;\r\n      sum += val;\r\n      sumSq += val * val;\r\n      count++;\r\n    }\r\n  }\r\n\r\n  if (count <= 1) return 0;\r\n  const mean = sum / count;\r\n  return (sumSq / count) - (mean * mean);\r\n}\r\n\r\n/**\r\n * Analyzes document and text skew using Radon / Horizontal Projection Profile variance.\r\n *\r\n * @param input - File path, Buffer, or Uint8Array representing an image.\r\n * @param options - Configurable parameters.\r\n * @returns Promise resolving to a SkewResult.\r\n */\r\nexport async function analyzeSkew(\r\n  input: string | Buffer | Uint8Array,\r\n  options?: SkewOptions\r\n): Promise<SkewResult> {\r\n  const opts = normalizeOptions(options);\r\n\r\n  // Load image, grayscale, downsample\r\n  const { data: rawGray, info } = await sharp(input)\r\n    .resize({ width: opts.downsampleWidth, withoutEnlargement: true })\r\n    .grayscale()\r\n    .raw()\r\n    .toBuffer({ resolveWithObject: true });\r\n\r\n  const width = info.width;\r\n  const height = info.height;\r\n  const totalPixels = width * height;\r\n\r\n  if (totalPixels === 0) {\r\n    throw new Error('Image contains no pixel data.');\r\n  }\r\n\r\n  // Fast Sobel horizontal edge filtering (horizontal edges are most sensitive to tilt)\r\n  const edges = new Uint8Array(totalPixels);\r\n  for (let y = 1; y < height - 1; y++) {\r\n    const rPrev = (y - 1) * width;\r\n    const rCurr = y * width;\r\n    const rNext = (y + 1) * width;\r\n\r\n    for (let x = 1; x < width - 1; x++) {\r\n      // Sobel Y (horizontal gradients)\r\n      const gy =\r\n        -(rawGray[rPrev + x - 1]! + 2 * rawGray[rPrev + x]! + rawGray[rPrev + x + 1]!) +\r\n        (rawGray[rNext + x - 1]! + 2 * rawGray[rNext + x]! + rawGray[rNext + x + 1]!);\r\n\r\n      const mag = Math.abs(gy);\r\n      // Threshold edges to binary structure\r\n      edges[rCurr + x] = mag > 45 ? 255 : 0;\r\n    }\r\n  }\r\n\r\n  // Angular sweep to find peak variance\r\n  let bestAngle = 0;\r\n  let maxVariance = -1;\r\n  let minVariance = Infinity;\r\n  let zeroAngleVariance = 0;\r\n\r\n  const startAngle = -opts.maxAngle;\r\n  const endAngle = opts.maxAngle;\r\n  const step = opts.angleStep;\r\n\r\n  const variances: { angle: number; variance: number }[] = [];\r\n\r\n  for (let angle = startAngle; angle <= endAngle; angle += step) {\r\n    const roundedAngle = Math.round(angle * 100) / 100;\r\n    const variance = evaluateProjectionVariance(edges, width, height, roundedAngle);\r\n\r\n    variances.push({ angle: roundedAngle, variance });\r\n\r\n    if (roundedAngle === 0) {\r\n      zeroAngleVariance = variance;\r\n    }\r\n\r\n    if (variance > maxVariance) {\r\n      maxVariance = variance;\r\n      bestAngle = roundedAngle;\r\n    }\r\n    if (variance < minVariance) {\r\n      minVariance = variance;\r\n    }\r\n  }\r\n\r\n  // Compute confidence based on contrast between peak variance and baseline variance\r\n  const baseline = (minVariance === Infinity || minVariance < 0) ? 0 : minVariance;\r\n  const peakContrast = maxVariance > baseline && baseline > 0\r\n    ? (maxVariance - baseline) / maxVariance\r\n    : 0;\r\n\r\n  const confidence = Number(Math.min(1.0, Math.max(0.0, peakContrast)).toFixed(3));\r\n\r\n  // If confidence is too low (e.g. blank page or uniform texture), assume 0 skew\r\n  const finalAngle = confidence >= opts.minConfidence ? bestAngle : 0;\r\n  const absAngle = Math.abs(finalAngle);\r\n\r\n  // Normalized score (0.0 = 0 deg, 1.0 = 45+ deg)\r\n  const score = Number(Math.min(1.0, absAngle / 45).toFixed(4));\r\n  const isSkewed = absAngle >= opts.angleThreshold;\r\n\r\n  // Corrective rotation is opposite of detected angle\r\n  const correctiveRotation = finalAngle === 0 ? 0 : Number((-finalAngle).toFixed(2));\r\n\r\n  let quality: 'straight' | 'slight-tilt' | 'moderate-skew' | 'severe-skew';\r\n  if (absAngle < 1.0) {\r\n    quality = 'straight';\r\n  } else if (absAngle <= opts.angleThreshold) {\r\n    quality = 'slight-tilt';\r\n  } else if (absAngle <= 15.0) {\r\n    quality = 'moderate-skew';\r\n  } else {\r\n    quality = 'severe-skew';\r\n  }\r\n\r\n  const details: SkewDetails = {\r\n    angle: finalAngle,\r\n    confidence,\r\n    width,\r\n    height\r\n  };\r\n\r\n  return {\r\n    angle: finalAngle,\r\n    score,\r\n    isSkewed,\r\n    confidence,\r\n    correctiveRotation,\r\n    quality,\r\n    details\r\n  };\r\n}\r\n\r\n/**\r\n * Returns only the detected skew angle in degrees.\r\n */\r\nexport async function getSkewAngle(\r\n  input: string | Buffer | Uint8Array,\r\n  options?: SkewOptions\r\n): Promise<number> {\r\n  const res = await analyzeSkew(input, options);\r\n  return res.angle;\r\n}\r\n\r\n/**\r\n * Returns true if the image exceeds the skew threshold.\r\n */\r\nexport async function isSkewed(\r\n  input: string | Buffer | Uint8Array,\r\n  threshold?: number\r\n): Promise<boolean> {\r\n  const options: SkewOptions = {};\r\n  if (threshold !== undefined) {\r\n    options.angleThreshold = threshold;\r\n  }\r\n  const res = await analyzeSkew(input, options);\r\n  return res.isSkewed;\r\n}\r\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "skew-score",
+  "version": "1.0.0",
+  "description": "Quantifies document and image tilt/skew angle (-45° to +45°) using Radon projection profile analysis via Sharp. Optimized for pre-OCR document scanning, KYC ID verification, and receipt processing.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "skew",
+    "skew-score",
+    "deskew",
+    "rotation",
+    "tilt-detection",
+    "image-processing",
+    "ocr-preprocessing",
+    "kyc-document",
+    "sharp",
+    "blur-score",
+    "exposure-score",
+    "glare-score",
+    "contrast-score"
+  ],
+  "author": "Vijay Misal <misalvijay153@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vjymisal0/skew-score.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vjymisal0/skew-score/issues"
+  },
+  "homepage": "https://github.com/vjymisal0/skew-score#readme",
+  "license": "MIT",
+  "dependencies": {
+    "sharp": "^0.33.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}