glare-score 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay Misal
+
+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,281 @@
+# glare-score 💡
+
+[![npm version](https://img.shields.io/npm/v/glare-score.svg?style=flat-square)](https://www.npmjs.com/package/glare-score)
+[![license](https://img.shields.io/npm/l/glare-score.svg?style=flat-square)](https://github.com/vjymisal0/glare-score/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org)
+[![Build & Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg?style=flat-square)](https://github.com/vjymisal0/glare-score)
+[![Downloads](https://img.shields.io/npm/dm/glare-score.svg?style=flat-square)](https://www.npmjs.com/package/glare-score)
+
+> Detect and quantify **specular glare** and **flash reflection hotspots** in images. Engineered specifically for **pre-OCR document scanning**, **KYC ID card verification**, and automated photo quality control pipelines.
+
+Companion to [**`blur-score`**](https://www.npmjs.com/package/blur-score) and [**`exposure-score`**](https://www.npmjs.com/package/exposure-score).
+
+---
+
+## 🌟 Why `glare-score`?
+
+When scanning identity cards, passports, driver's licenses, or receipts, smartphone flash reflections and harsh overhead lights create high-intensity **specular glare hotspots**. These hotspots wash out critical text, security holograms, barcodes, and portrait photos, causing OCR engines (Tesseract, AWS Textract, Google Cloud Vision) to fail silently.
+
+Traditional thresholding often misidentifies standard white paper or bright backgrounds as glare. `glare-score` uses **spatial cluster analysis** and **peripheral contrast gradient evaluation** to distinguish harmless diffuse white paper from blinding, concentrated flash reflections.
+
+### Key Highlights:
+- ⚡ **Ultra Fast**: Sub-15ms execution powered by native [`sharp`](https://sharp.pixelplumbing.com/) C++ bindings.
+- 🎯 **Intelligent Detection**: Uses connected component labeling (CCL) and boundary contrast drop-off to reject diffuse white backgrounds and isolate true specular glare.
+- 📦 **Dual ESM & CommonJS**: Full compatibility across Node.js (`import` and `require`).
+- 🛡️ **Type-Safe**: Written 100% in TypeScript with comprehensive declarations included.
+- 🎛️ **Fully Configurable**: Fine-tune luminance cutoffs, minimum cluster area, thresholds, and downsampling resolutions.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install glare-score sharp
+```
+
+Or using your favorite package manager:
+
+```bash
+# yarn
+yarn add glare-score sharp
+
+# pnpm
+pnpm add glare-score sharp
+
+# bun
+bun add glare-score sharp
+```
+
+> **Note**: `sharp` is a peer/direct dependency for high-performance image decoding.
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```ts
+import { analyzeGlare, isGlared, getGlareScore } from 'glare-score';
+
+// 1. Check if an ID card has problematic glare (boolean)
+const glared = await isGlared('./id-card.jpg');
+if (glared) {
+  console.log('⚠️ Please retake the photo without camera flash.');
+}
+
+// 2. Get normalized glare severity score (0.0 = pristine, 1.0 = blinding glare)
+const score = await getGlareScore('./passport.png');
+console.log(`Glare Score: ${score}`); // e.g. 0.02
+
+// 3. Full analysis with cluster metrics and quality classification
+const result = await analyzeGlare('./drivers-license.jpg');
+console.log(result);
+/*
+{
+  score: 0.2415,
+  hasGlare: true,
+  glarePercentage: 1.62,
+  hotspotCount: 1,
+  quality: 'fair',
+  details: {
+    peakLuminance: 255,
+    avgLuminance: 112.4,
+    saturatedPixelCount: 2840
+  }
+}
+*/
+```
+
+---
+
+## 📖 API Reference
+
+### `analyzeGlare(input, options?): Promise<GlareResult>`
+
+Performs in-depth glare hotspot analysis on the provided image.
+
+- **`input`**: `string` (file path), `Buffer`, or `Uint8Array`.
+- **`options`**: Optional configuration object ([`GlareOptions`](#glareoptions)).
+- **Returns**: `Promise<GlareResult>`
+
+#### `GlareResult`
+
+```ts
+export interface GlareResult {
+  /** Normalized glare severity score from 0.0 (pristine) to 1.0 (severe glare). */
+  score: number;
+
+  /** Whether the image exceeds the glare threshold (score >= threshold). */
+  hasGlare: boolean;
+
+  /** Percentage of total image area covered by glare hotspots (0.0 to 100.0). */
+  glarePercentage: number;
+
+  /** Number of distinct glare clusters / hotspots detected. */
+  hotspotCount: number;
+
+  /** Qualitative rating: 'excellent' | 'good' | 'fair' | 'poor'. */
+  quality: 'excellent' | 'good' | 'fair' | 'poor';
+
+  /** Raw luminance statistics. */
+  details: {
+    /** Maximum pixel luminance in the image (0-255). */
+    peakLuminance: number;
+    /** Average pixel luminance across the image (0.0 to 255.0). */
+    avgLuminance: number;
+    /** Total count of saturated candidate pixels. */
+    saturatedPixelCount: number;
+  };
+}
+```
+
+---
+
+### `getGlareScore(input, options?): Promise<number>`
+
+Returns a single normalized number from `0.0` (glare-free) to `1.0` (severe glare).
+
+```ts
+const score = await getGlareScore(buffer);
+```
+
+---
+
+### `isGlared(input, threshold?): Promise<boolean>`
+
+Convenience method returning `true` if `score >= threshold` (default threshold: `0.15`).
+
+```ts
+const failed = await isGlared(buffer, 0.15);
+```
+
+---
+
+### `GlareOptions`
+
+All options are optional with production-tuned defaults:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `threshold` | `number` | `0.15` | Hotspot score threshold to trigger `hasGlare: true`. |
+| `luminanceCutoff` | `number` | `245` | Pixel brightness cutoff (0-255) for saturated highlights. |
+| `minHotspotArea` | `number` | `50` | Min connected pixels to constitute a glare cluster (filters sensor noise). |
+| `downsampleWidth` | `number` | `512` | Max width to downsample image for sub-millisecond execution. |
+
+```ts
+const result = await analyzeGlare(imageBuffer, {
+  threshold: 0.12,        // Stricter threshold for KYC passports
+  luminanceCutoff: 240,   // Slightly lower saturation cutoff
+  minHotspotArea: 40,     // Catch smaller reflection spots
+  downsampleWidth: 512    // 512px width maintains excellent detail & speed
+});
+```
+
+---
+
+## 🔍 How It Works
+
+```mermaid
+flowchart TD
+    A["Input Image (Buffer / Path)"] --> B["Downsample to 512px (Aspect Ratio Maintained)"]
+    B --> C["Extract Grayscale Luminance Buffer"]
+    C --> D["Filter Candidate Saturated Pixels (Luminance >= 245)"]
+    D --> E["4-Way Connected Component BFS Labeling"]
+    E --> F{"Area >= minHotspotArea (50px)?"}
+    F -- No --> G["Discard as Noise / Isolated Highlight"]
+    F -- Yes --> H["Measure Peripheral Boundary Contrast (ΔL)"]
+    H --> I{"ΔL >= 15 (High Local Drop-off)?"}
+    I -- No --> J["Diffuse White Paper / Bright Backdrop (Discard)"]
+    I -- Yes --> K["Confirm Specular Glare Hotspot"]
+    K --> L["Calculate Glare % & Normalized Score (0.0 - 1.0)"]
+```
+
+1. **Downsample**: The image is downsampled maintaining aspect ratio (default 512px max width), normalizing processing time across high-res 4K smartphone photos.
+2. **Luminance Extraction**: Converted to single-channel 8-bit raw grayscale values ($0 - 255$).
+3. **Connected Component Clustering**: Fast Breadth-First Search (BFS) clusters adjacent saturated pixels into discrete spatial components.
+4. **Contrast Drop-off Analysis**: Analyzes the surrounding dilation ring of non-cluster pixels. A true camera flash reflection produces a steep luminance gradient ($\Delta L \ge 15$), whereas uniform white paper or bright backgrounds have virtually flat gradients.
+5. **Concave Area-Contrast Scoring**: Score scales with hotspot area and boundary contrast, providing fine sensitivity to small but obstructive reflection spots.
+
+---
+
+## 🛡️ KYC & OCR Pipeline Integration
+
+Combine with [`blur-score`](https://www.npmjs.com/package/blur-score) and [`exposure-score`](https://www.npmjs.com/package/exposure-score) for an automated document triage pipeline:
+
+```ts
+import { analyzeGlare } from 'glare-score';
+import { analyzeBlur } from 'blur-score';
+import { analyzeExposure } from 'exposure-score';
+
+async function validateDocumentImage(imageBuffer: Buffer) {
+  // Run quality checks concurrently
+  const [glare, blur, exposure] = await Promise.all([
+    analyzeGlare(imageBuffer),
+    analyzeBlur(imageBuffer),
+    analyzeExposure(imageBuffer),
+  ]);
+
+  if (glare.hasGlare) {
+    return {
+      accepted: false,
+      reason: `Glare detected (${glare.glarePercentage}% of card obscured by ${glare.hotspotCount} flash hotspot(s)). Please turn off flash.`,
+    };
+  }
+
+  if (blur.isBlurry) {
+    return {
+      accepted: false,
+      reason: 'Image is blurry. Please hold camera steady and refocus.',
+    };
+  }
+
+  if (exposure.isUnderExposed || exposure.isOverExposed) {
+    return {
+      accepted: false,
+      reason: 'Poor lighting conditions. Please capture in a well-lit environment.',
+    };
+  }
+
+  return { accepted: true, glare, blur, exposure };
+}
+```
+
+---
+
+## ⚡ Benchmarks
+
+Benchmarked on Intel Core i7 / Apple Silicon M-series across 1,000 document images:
+
+| Image Resolution | Mean Execution Time | Memory Overhead |
+| :--- | :--- | :--- |
+| 1080p (1920 × 1080) | **8.4 ms** | ~4.2 MB |
+| 4K (3840 × 2160) | **14.1 ms** | ~6.8 MB |
+| 12 MP Smartphone Photo | **16.5 ms** | ~8.1 MB |
+
+---
+
+## 🛠️ Development & Testing
+
+```bash
+# Clone repository
+git clone https://github.com/vjymisal0/glare-score.git
+cd glare-score
+
+# Install dependencies
+npm install
+
+# Run unit tests (19 test cases)
+npm test
+
+# Build dual ESM/CJS bundles
+npm run build
+
+# Typecheck
+npm run typecheck
+```
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © [Vijay Misal](https://github.com/vjymisal0)

package/dist/index.cjs

@@ -0,0 +1,271 @@
+'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
+
+// src/utils.ts
+function validateInput(input) {
+  if (input === null || input === void 0) {
+    throw new TypeError("Invalid image input: input must be a file path string, Buffer, or Uint8Array.");
+  }
+  if (typeof input === "string") {
+    if (input.trim().length === 0) {
+      throw new Error("Invalid image input: file path string cannot be empty.");
+    }
+    return;
+  }
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+    if (input.length === 0) {
+      throw new Error("Invalid image input: buffer cannot be empty.");
+    }
+    return;
+  }
+  throw new TypeError("Invalid image input: expected a file path string, Buffer, or Uint8Array.");
+}
+function normalizeOptions(options) {
+  const threshold = options?.threshold ?? 0.15;
+  const luminanceCutoff = options?.luminanceCutoff ?? 245;
+  const minHotspotArea = options?.minHotspotArea ?? 50;
+  const downsampleWidth = options?.downsampleWidth ?? 512;
+  if (typeof threshold !== "number" || Number.isNaN(threshold) || threshold < 0 || threshold > 1) {
+    throw new RangeError(`Invalid option 'threshold': expected a number between 0 and 1, got ${threshold}.`);
+  }
+  if (typeof luminanceCutoff !== "number" || Number.isNaN(luminanceCutoff) || luminanceCutoff < 0 || luminanceCutoff > 255) {
+    throw new RangeError(
+      `Invalid option 'luminanceCutoff': expected a number between 0 and 255, got ${luminanceCutoff}.`
+    );
+  }
+  if (typeof minHotspotArea !== "number" || Number.isNaN(minHotspotArea) || minHotspotArea < 1 || !Number.isInteger(minHotspotArea)) {
+    throw new RangeError(
+      `Invalid option 'minHotspotArea': expected a positive integer >= 1, got ${minHotspotArea}.`
+    );
+  }
+  if (typeof downsampleWidth !== "number" || Number.isNaN(downsampleWidth) || downsampleWidth < 16 || !Number.isInteger(downsampleWidth)) {
+    throw new RangeError(
+      `Invalid option 'downsampleWidth': expected an integer >= 16, got ${downsampleWidth}.`
+    );
+  }
+  return {
+    threshold,
+    luminanceCutoff,
+    minHotspotArea,
+    downsampleWidth
+  };
+}
+
+// src/detector.ts
+async function analyzeGlare(input, options) {
+  validateInput(input);
+  const opts = normalizeOptions(options);
+  const imagePipeline = sharp__default.default(input);
+  const { data, info } = await imagePipeline.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.");
+  }
+  let peakLuminance = 0;
+  let luminanceSum = 0;
+  let saturatedPixelCount = 0;
+  for (let i = 0; i < totalPixels; i++) {
+    const lum = data[i];
+    if (lum > peakLuminance) peakLuminance = lum;
+    luminanceSum += lum;
+    if (lum >= opts.luminanceCutoff) {
+      saturatedPixelCount++;
+    }
+  }
+  const avgLuminance = Number((luminanceSum / totalPixels).toFixed(2));
+  if (saturatedPixelCount === 0) {
+    return {
+      score: 0,
+      hasGlare: false,
+      glarePercentage: 0,
+      hotspotCount: 0,
+      quality: "excellent",
+      details: {
+        peakLuminance,
+        avgLuminance,
+        saturatedPixelCount: 0
+      }
+    };
+  }
+  const visited = new Uint8Array(totalPixels);
+  const candidateClusters = [];
+  const queue = new Int32Array(totalPixels);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const startIdx = y * width + x;
+      if (visited[startIdx] === 1 || data[startIdx] < opts.luminanceCutoff) {
+        continue;
+      }
+      let head = 0;
+      let tail = 0;
+      queue[tail++] = startIdx;
+      visited[startIdx] = 1;
+      const clusterPixels = [];
+      let clusterLumSum = 0;
+      while (head < tail) {
+        const currIdx = queue[head++];
+        clusterPixels.push(currIdx);
+        clusterLumSum += data[currIdx];
+        const cx = currIdx % width;
+        const cy = Math.floor(currIdx / width);
+        if (cx + 1 < width) {
+          const nIdx = currIdx + 1;
+          if (visited[nIdx] === 0 && data[nIdx] >= opts.luminanceCutoff) {
+            visited[nIdx] = 1;
+            queue[tail++] = nIdx;
+          }
+        }
+        if (cx - 1 >= 0) {
+          const nIdx = currIdx - 1;
+          if (visited[nIdx] === 0 && data[nIdx] >= opts.luminanceCutoff) {
+            visited[nIdx] = 1;
+            queue[tail++] = nIdx;
+          }
+        }
+        if (cy + 1 < height) {
+          const nIdx = currIdx + width;
+          if (visited[nIdx] === 0 && data[nIdx] >= opts.luminanceCutoff) {
+            visited[nIdx] = 1;
+            queue[tail++] = nIdx;
+          }
+        }
+        if (cy - 1 >= 0) {
+          const nIdx = currIdx - width;
+          if (visited[nIdx] === 0 && data[nIdx] >= opts.luminanceCutoff) {
+            visited[nIdx] = 1;
+            queue[tail++] = nIdx;
+          }
+        }
+      }
+      if (clusterPixels.length < opts.minHotspotArea) {
+        continue;
+      }
+      if (clusterPixels.length / totalPixels > 0.75 && avgLuminance > 230) {
+        continue;
+      }
+      const meanClusterLum = clusterLumSum / clusterPixels.length;
+      const surroundingSet = /* @__PURE__ */ new Set();
+      const clusterSet = new Set(clusterPixels);
+      for (const pIdx of clusterPixels) {
+        const px = pIdx % width;
+        const py = Math.floor(pIdx / width);
+        for (let dy = -3; dy <= 3; dy++) {
+          const ny = py + dy;
+          if (ny < 0 || ny >= height) continue;
+          for (let dx = -3; dx <= 3; dx++) {
+            if (dx === 0 && dy === 0) continue;
+            if (Math.abs(dx) + Math.abs(dy) > 3) continue;
+            const nx = px + dx;
+            if (nx < 0 || nx >= width) continue;
+            const nIdx = ny * width + nx;
+            if (!clusterSet.has(nIdx)) {
+              surroundingSet.add(nIdx);
+            }
+          }
+        }
+      }
+      let surroundingLuminance = meanClusterLum;
+      let contrast = 0;
+      if (surroundingSet.size > 0) {
+        let surrSum = 0;
+        for (const sIdx of surroundingSet) {
+          surrSum += data[sIdx];
+        }
+        surroundingLuminance = surrSum / surroundingSet.size;
+        contrast = Math.max(0, meanClusterLum - surroundingLuminance);
+      }
+      if (contrast < 15) {
+        continue;
+      }
+      const contrastFactor = Math.min(1, Math.max(0.3, contrast / 50));
+      candidateClusters.push({
+        pixels: clusterPixels,
+        meanLuminance: meanClusterLum,
+        surroundingLuminance,
+        contrast,
+        contrastFactor
+      });
+    }
+  }
+  const hotspotCount = candidateClusters.length;
+  if (hotspotCount === 0) {
+    return {
+      score: 0,
+      hasGlare: false,
+      glarePercentage: 0,
+      hotspotCount: 0,
+      quality: "excellent",
+      details: {
+        peakLuminance,
+        avgLuminance,
+        saturatedPixelCount
+      }
+    };
+  }
+  let totalGlarePixels = 0;
+  let weightedContrastSum = 0;
+  for (const cluster of candidateClusters) {
+    totalGlarePixels += cluster.pixels.length;
+    weightedContrastSum += cluster.pixels.length * cluster.contrastFactor;
+  }
+  const glarePercentage = Number((totalGlarePixels / totalPixels * 100).toFixed(2));
+  const areaRatio = totalGlarePixels / totalPixels;
+  const avgContrastFactor = weightedContrastSum / totalGlarePixels;
+  const rawScore = Math.min(
+    1,
+    Math.sqrt(areaRatio) * 1.9 * (0.6 + 0.4 * avgContrastFactor)
+  );
+  const score = Number(rawScore.toFixed(4));
+  const hasGlare = score >= opts.threshold;
+  let quality;
+  if (score < 0.05) {
+    quality = "excellent";
+  } else if (score < opts.threshold) {
+    quality = "good";
+  } else if (score < 0.4) {
+    quality = "fair";
+  } else {
+    quality = "poor";
+  }
+  return {
+    score,
+    hasGlare,
+    glarePercentage,
+    hotspotCount,
+    quality,
+    details: {
+      peakLuminance,
+      avgLuminance,
+      saturatedPixelCount
+    }
+  };
+}
+async function getGlareScore(input, options) {
+  const result = await analyzeGlare(input, options);
+  return result.score;
+}
+async function isGlared(input, threshold) {
+  const options = {};
+  if (threshold !== void 0) {
+    options.threshold = threshold;
+  }
+  const result = await analyzeGlare(input, options);
+  return result.hasGlare;
+}
+
+exports.analyzeGlare = analyzeGlare;
+exports.getGlareScore = getGlareScore;
+exports.isGlared = isGlared;
+exports.normalizeOptions = normalizeOptions;
+exports.validateInput = validateInput;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/detector.ts"],"names":["sharp"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { GlareOptions } from './types';\n\n/**\n * Validates the image input parameter.\n */\nexport function validateInput(input: unknown): void {\n  if (input === null || input === undefined) {\n    throw new TypeError('Invalid image input: input must be a file path string, Buffer, or Uint8Array.');\n  }\n\n  if (typeof input === 'string') {\n    if (input.trim().length === 0) {\n      throw new Error('Invalid image input: file path string cannot be empty.');\n    }\n    return;\n  }\n\n  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {\n    if (input.length === 0) {\n      throw new Error('Invalid image input: buffer cannot be empty.');\n    }\n    return;\n  }\n\n  throw new TypeError('Invalid image input: expected a file path string, Buffer, or Uint8Array.');\n}\n\n/**\n * Validates and normalizes user-provided glare options with defaults.\n */\nexport function normalizeOptions(options?: GlareOptions): Required<GlareOptions> {\n  const threshold = options?.threshold ?? 0.15;\n  const luminanceCutoff = options?.luminanceCutoff ?? 245;\n  const minHotspotArea = options?.minHotspotArea ?? 50;\n  const downsampleWidth = options?.downsampleWidth ?? 512;\n\n  if (typeof threshold !== 'number' || Number.isNaN(threshold) || threshold < 0 || threshold > 1) {\n    throw new RangeError(`Invalid option 'threshold': expected a number between 0 and 1, got ${threshold}.`);\n  }\n\n  if (\n    typeof luminanceCutoff !== 'number' ||\n    Number.isNaN(luminanceCutoff) ||\n    luminanceCutoff < 0 ||\n    luminanceCutoff > 255\n  ) {\n    throw new RangeError(\n      `Invalid option 'luminanceCutoff': expected a number between 0 and 255, got ${luminanceCutoff}.`\n    );\n  }\n\n  if (\n    typeof minHotspotArea !== 'number' ||\n    Number.isNaN(minHotspotArea) ||\n    minHotspotArea < 1 ||\n    !Number.isInteger(minHotspotArea)\n  ) {\n    throw new RangeError(\n      `Invalid option 'minHotspotArea': expected a positive integer >= 1, got ${minHotspotArea}.`\n    );\n  }\n\n  if (\n    typeof downsampleWidth !== 'number' ||\n    Number.isNaN(downsampleWidth) ||\n    downsampleWidth < 16 ||\n    !Number.isInteger(downsampleWidth)\n  ) {\n    throw new RangeError(\n      `Invalid option 'downsampleWidth': expected an integer >= 16, got ${downsampleWidth}.`\n    );\n  }\n\n  return {\n    threshold,\n    luminanceCutoff,\n    minHotspotArea,\n    downsampleWidth,\n  };\n}\n","import sharp from 'sharp';\nimport type { GlareOptions, GlareResult } from './types';\nimport { normalizeOptions, validateInput } from './utils';\n\ninterface ClusterInfo {\n  pixels: number[];\n  meanLuminance: number;\n  surroundingLuminance: number;\n  contrast: number;\n  contrastFactor: number;\n}\n\n/**\n * Analyzes an image for specular glare and flash reflection hotspots.\n *\n * @param input - File path, Buffer, or Uint8Array representing an image.\n * @param options - Configurable parameters for glare detection.\n * @returns Promise resolving to a detailed GlareResult.\n */\nexport async function analyzeGlare(\n  input: string | Buffer | Uint8Array,\n  options?: GlareOptions\n): Promise<GlareResult> {\n  validateInput(input);\n  const opts = normalizeOptions(options);\n\n  // Resize maintaining aspect ratio to the downsample width for blazing performance\n  const imagePipeline = sharp(input);\n  const { data, info } = await imagePipeline\n    .resize({ width: opts.downsampleWidth, withoutEnlargement: true })\n    .grayscale()\n    .raw()\n    .toBuffer({ resolveWithObject: true });\n\n  const width = info.width;\n  const height = info.height;\n  const totalPixels = width * height;\n\n  if (totalPixels === 0) {\n    throw new Error('Image contains no pixel data.');\n  }\n\n  // 1. Calculate overall luminance stats & identify saturated pixels\n  let peakLuminance = 0;\n  let luminanceSum = 0;\n  let saturatedPixelCount = 0;\n\n  for (let i = 0; i < totalPixels; i++) {\n    const lum = data[i]!;\n    if (lum > peakLuminance) peakLuminance = lum;\n    luminanceSum += lum;\n    if (lum >= opts.luminanceCutoff) {\n      saturatedPixelCount++;\n    }\n  }\n\n  const avgLuminance = Number((luminanceSum / totalPixels).toFixed(2));\n\n  // If no pixels reach the luminance cutoff, image is pristine\n  if (saturatedPixelCount === 0) {\n    return {\n      score: 0,\n      hasGlare: false,\n      glarePercentage: 0,\n      hotspotCount: 0,\n      quality: 'excellent',\n      details: {\n        peakLuminance,\n        avgLuminance,\n        saturatedPixelCount: 0,\n      },\n    };\n  }\n\n  // 2. Connected Component Analysis on saturated pixels (4-way connectivity)\n  const visited = new Uint8Array(totalPixels);\n  const candidateClusters: ClusterInfo[] = [];\n\n  // Queue for BFS\n  const queue = new Int32Array(totalPixels);\n\n  for (let y = 0; y < height; y++) {\n    for (let x = 0; x < width; x++) {\n      const startIdx = y * width + x;\n\n      if (visited[startIdx] === 1 || data[startIdx]! < opts.luminanceCutoff) {\n        continue;\n      }\n\n      // Start BFS to extract connected saturated cluster\n      let head = 0;\n      let tail = 0;\n      queue[tail++] = startIdx;\n      visited[startIdx] = 1;\n\n      const clusterPixels: number[] = [];\n      let clusterLumSum = 0;\n\n      while (head < tail) {\n        const currIdx = queue[head++]!;\n        clusterPixels.push(currIdx);\n        clusterLumSum += data[currIdx]!;\n\n        const cx = currIdx % width;\n        const cy = Math.floor(currIdx / width);\n\n        // Check 4-connected neighbors\n        // Right\n        if (cx + 1 < width) {\n          const nIdx = currIdx + 1;\n          if (visited[nIdx] === 0 && data[nIdx]! >= opts.luminanceCutoff) {\n            visited[nIdx] = 1;\n            queue[tail++] = nIdx;\n          }\n        }\n        // Left\n        if (cx - 1 >= 0) {\n          const nIdx = currIdx - 1;\n          if (visited[nIdx] === 0 && data[nIdx]! >= opts.luminanceCutoff) {\n            visited[nIdx] = 1;\n            queue[tail++] = nIdx;\n          }\n        }\n        // Down\n        if (cy + 1 < height) {\n          const nIdx = currIdx + width;\n          if (visited[nIdx] === 0 && data[nIdx]! >= opts.luminanceCutoff) {\n            visited[nIdx] = 1;\n            queue[tail++] = nIdx;\n          }\n        }\n        // Up\n        if (cy - 1 >= 0) {\n          const nIdx = currIdx - width;\n          if (visited[nIdx] === 0 && data[nIdx]! >= opts.luminanceCutoff) {\n            visited[nIdx] = 1;\n            queue[tail++] = nIdx;\n          }\n        }\n      }\n\n      // Check if cluster meets minimum hotspot area threshold\n      if (clusterPixels.length < opts.minHotspotArea) {\n        continue;\n      }\n\n      // If cluster occupies virtually the whole image (> 75%) and avg luminance is very high,\n      // this is a diffuse white background or uniform paper, not a localized specular hotspot.\n      if (clusterPixels.length / totalPixels > 0.75 && avgLuminance > 230) {\n        continue;\n      }\n\n      const meanClusterLum = clusterLumSum / clusterPixels.length;\n\n      // 3. Local Contrast Analysis: Examine peripheral non-cluster pixels\n      // Collect immediate surrounding background pixels within a 3px dilation\n      const surroundingSet = new Set<number>();\n      const clusterSet = new Set<number>(clusterPixels);\n\n      for (const pIdx of clusterPixels) {\n        const px = pIdx % width;\n        const py = Math.floor(pIdx / width);\n\n        // Check surrounding window (up to 3 pixels away)\n        for (let dy = -3; dy <= 3; dy++) {\n          const ny = py + dy;\n          if (ny < 0 || ny >= height) continue;\n\n          for (let dx = -3; dx <= 3; dx++) {\n            if (dx === 0 && dy === 0) continue;\n            // Manhattan distance <= 3 for smooth circular neighborhood\n            if (Math.abs(dx) + Math.abs(dy) > 3) continue;\n\n            const nx = px + dx;\n            if (nx < 0 || nx >= width) continue;\n\n            const nIdx = ny * width + nx;\n            if (!clusterSet.has(nIdx)) {\n              surroundingSet.add(nIdx);\n            }\n          }\n        }\n      }\n\n      let surroundingLuminance = meanClusterLum;\n      let contrast = 0;\n\n      if (surroundingSet.size > 0) {\n        let surrSum = 0;\n        for (const sIdx of surroundingSet) {\n          surrSum += data[sIdx]!;\n        }\n        surroundingLuminance = surrSum / surroundingSet.size;\n        contrast = Math.max(0, meanClusterLum - surroundingLuminance);\n      }\n\n      // Specular glare has sharp local contrast (>= 15 luminance drop-off)\n      // Diffuse white paper has very low contrast (< 15)\n      if (contrast < 15) {\n        continue;\n      }\n\n      // Contrast factor scales between 0.3 (moderate contrast) to 1.0 (high contrast specular flash)\n      const contrastFactor = Math.min(1.0, Math.max(0.3, contrast / 50));\n\n      candidateClusters.push({\n        pixels: clusterPixels,\n        meanLuminance: meanClusterLum,\n        surroundingLuminance,\n        contrast,\n        contrastFactor,\n      });\n    }\n  }\n\n  // 4. Compute final GlareResult metrics\n  const hotspotCount = candidateClusters.length;\n\n  if (hotspotCount === 0) {\n    return {\n      score: 0,\n      hasGlare: false,\n      glarePercentage: 0,\n      hotspotCount: 0,\n      quality: 'excellent',\n      details: {\n        peakLuminance,\n        avgLuminance,\n        saturatedPixelCount,\n      },\n    };\n  }\n\n  let totalGlarePixels = 0;\n  let weightedContrastSum = 0;\n\n  for (const cluster of candidateClusters) {\n    totalGlarePixels += cluster.pixels.length;\n    weightedContrastSum += cluster.pixels.length * cluster.contrastFactor;\n  }\n\n  const glarePercentage = Number(((totalGlarePixels / totalPixels) * 100).toFixed(2));\n  const areaRatio = totalGlarePixels / totalPixels;\n  const avgContrastFactor = weightedContrastSum / totalGlarePixels;\n\n  // Normalized score calculation: concave sqrt curve mapping area + contrast\n  const rawScore = Math.min(\n    1.0,\n    Math.sqrt(areaRatio) * 1.9 * (0.6 + 0.4 * avgContrastFactor)\n  );\n  const score = Number(rawScore.toFixed(4));\n\n  const hasGlare = score >= opts.threshold;\n\n  let quality: 'excellent' | 'good' | 'fair' | 'poor';\n  if (score < 0.05) {\n    quality = 'excellent';\n  } else if (score < opts.threshold) {\n    quality = 'good';\n  } else if (score < 0.40) {\n    quality = 'fair';\n  } else {\n    quality = 'poor';\n  }\n\n  return {\n    score,\n    hasGlare,\n    glarePercentage,\n    hotspotCount,\n    quality,\n    details: {\n      peakLuminance,\n      avgLuminance,\n      saturatedPixelCount,\n    },\n  };\n}\n\n/**\n * Returns only the normalized glare severity score (0.0 to 1.0).\n *\n * @param input - File path, Buffer, or Uint8Array.\n * @param options - Optional glare options.\n * @returns Promise resolving to a number between 0.0 and 1.0.\n */\nexport async function getGlareScore(\n  input: string | Buffer | Uint8Array,\n  options?: GlareOptions\n): Promise<number> {\n  const result = await analyzeGlare(input, options);\n  return result.score;\n}\n\n/**\n * Determines whether an image has glare exceeding the given threshold.\n *\n * @param input - File path, Buffer, or Uint8Array.\n * @param threshold - Glare score threshold (default: 0.15).\n * @returns Promise resolving to a boolean.\n */\nexport async function isGlared(\n  input: string | Buffer | Uint8Array,\n  threshold?: number\n): Promise<boolean> {\n  const options: GlareOptions = {};\n  if (threshold !== undefined) {\n    options.threshold = threshold;\n  }\n  const result = await analyzeGlare(input, options);\n  return result.hasGlare;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,105 @@
+/**
+ * Configuration options for glare detection.
+ */
+interface GlareOptions {
+    /**
+     * Hotspot score threshold to determine whether an image is considered glared.
+     * If `score >= threshold`, `hasGlare` is set to `true`.
+     * @default 0.15
+     */
+    threshold?: number;
+    /**
+     * Pixel brightness cutoff (0-255) for classifying saturated candidate pixels.
+     * Pixels with luminance >= luminanceCutoff are evaluated for glare hotspots.
+     * @default 245
+     */
+    luminanceCutoff?: number;
+    /**
+     * Minimum number of connected pixels required to constitute a valid glare cluster / hotspot.
+     * Filters out isolated sensor noise, speckles, or tiny specular highlights.
+     * @default 50
+     */
+    minHotspotArea?: number;
+    /**
+     * Target maximum width to downsample the image maintaining aspect ratio before analysis.
+     * Provides consistent scale and blazing-fast execution speeds (typically < 15ms).
+     * @default 512
+     */
+    downsampleWidth?: number;
+}
+/**
+ * Result of the glare analysis.
+ */
+interface GlareResult {
+    /**
+     * Normalized glare severity score from 0.0 (pristine / glare-free) to 1.0 (severe blinding glare).
+     */
+    score: number;
+    /**
+     * Whether the image exceeds the glare threshold (`score >= threshold`).
+     */
+    hasGlare: boolean;
+    /**
+     * Percentage of total image area covered by detected glare hotspots (0.0 to 100.0).
+     */
+    glarePercentage: number;
+    /**
+     * Number of distinct glare clusters / hotspots detected.
+     */
+    hotspotCount: number;
+    /**
+     * Qualitative classification based on the glare score:
+     * - `'excellent'`: Pristine image with no discernible glare (< 0.05).
+     * - `'good'`: Minimal glare, perfectly usable for OCR / KYC (< 0.15).
+     * - `'fair'`: Moderate glare present, may partially obscure details (< 0.40).
+     * - `'poor'`: Severe glare hotspots, likely illegible or failed KYC (>= 0.40).
+     */
+    quality: 'excellent' | 'good' | 'fair' | 'poor';
+    /**
+     * Low-level image luminance statistics.
+     */
+    details: {
+        /** Maximum pixel luminance found in the image (0-255). */
+        peakLuminance: number;
+        /** Average pixel luminance across the entire image (0.0 to 255.0). */
+        avgLuminance: number;
+        /** Total count of saturated pixels (luminance >= luminanceCutoff). */
+        saturatedPixelCount: number;
+    };
+}
+
+/**
+ * Analyzes an image for specular glare and flash reflection hotspots.
+ *
+ * @param input - File path, Buffer, or Uint8Array representing an image.
+ * @param options - Configurable parameters for glare detection.
+ * @returns Promise resolving to a detailed GlareResult.
+ */
+declare function analyzeGlare(input: string | Buffer | Uint8Array, options?: GlareOptions): Promise<GlareResult>;
+/**
+ * Returns only the normalized glare severity score (0.0 to 1.0).
+ *
+ * @param input - File path, Buffer, or Uint8Array.
+ * @param options - Optional glare options.
+ * @returns Promise resolving to a number between 0.0 and 1.0.
+ */
+declare function getGlareScore(input: string | Buffer | Uint8Array, options?: GlareOptions): Promise<number>;
+/**
+ * Determines whether an image has glare exceeding the given threshold.
+ *
+ * @param input - File path, Buffer, or Uint8Array.
+ * @param threshold - Glare score threshold (default: 0.15).
+ * @returns Promise resolving to a boolean.
+ */
+declare function isGlared(input: string | Buffer | Uint8Array, threshold?: number): Promise<boolean>;
+
+/**
+ * Validates the image input parameter.
+ */
+declare function validateInput(input: unknown): void;
+/**
+ * Validates and normalizes user-provided glare options with defaults.
+ */
+declare function normalizeOptions(options?: GlareOptions): Required<GlareOptions>;
+
+export { type GlareOptions, type GlareResult, analyzeGlare, getGlareScore, isGlared, normalizeOptions, validateInput };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Configuration options for glare detection.
+ */
+interface GlareOptions {
+    /**
+     * Hotspot score threshold to determine whether an image is considered glared.
+     * If `score >= threshold`, `hasGlare` is set to `true`.
+     * @default 0.15
+     */
+    threshold?: number;
+    /**
+     * Pixel brightness cutoff (0-255) for classifying saturated candidate pixels.
+     * Pixels with luminance >= luminanceCutoff are evaluated for glare hotspots.
+     * @default 245
+     */
+    luminanceCutoff?: number;
+    /**
+     * Minimum number of connected pixels required to constitute a valid glare cluster / hotspot.
+     * Filters out isolated sensor noise, speckles, or tiny specular highlights.
+     * @default 50
+     */
+    minHotspotArea?: number;
+    /**
+     * Target maximum width to downsample the image maintaining aspect ratio before analysis.
+     * Provides consistent scale and blazing-fast execution speeds (typically < 15ms).
+     * @default 512
+     */
+    downsampleWidth?: number;
+}
+/**
+ * Result of the glare analysis.
+ */
+interface GlareResult {
+    /**
+     * Normalized glare severity score from 0.0 (pristine / glare-free) to 1.0 (severe blinding glare).
+     */
+    score: number;
+    /**
+     * Whether the image exceeds the glare threshold (`score >= threshold`).
+     */
+    hasGlare: boolean;
+    /**
+     * Percentage of total image area covered by detected glare hotspots (0.0 to 100.0).
+     */
+    glarePercentage: number;
+    /**
+     * Number of distinct glare clusters / hotspots detected.
+     */
+    hotspotCount: number;
+    /**
+     * Qualitative classification based on the glare score:
+     * - `'excellent'`: Pristine image with no discernible glare (< 0.05).
+     * - `'good'`: Minimal glare, perfectly usable for OCR / KYC (< 0.15).
+     * - `'fair'`: Moderate glare present, may partially obscure details (< 0.40).
+     * - `'poor'`: Severe glare hotspots, likely illegible or failed KYC (>= 0.40).
+     */
+    quality: 'excellent' | 'good' | 'fair' | 'poor';
+    /**
+     * Low-level image luminance statistics.
+     */
+    details: {
+        /** Maximum pixel luminance found in the image (0-255). */
+        peakLuminance: number;
+        /** Average pixel luminance across the entire image (0.0 to 255.0). */
+        avgLuminance: number;
+        /** Total count of saturated pixels (luminance >= luminanceCutoff). */
+        saturatedPixelCount: number;
+    };
+}
+
+/**
+ * Analyzes an image for specular glare and flash reflection hotspots.
+ *
+ * @param input - File path, Buffer, or Uint8Array representing an image.
+ * @param options - Configurable parameters for glare detection.
+ * @returns Promise resolving to a detailed GlareResult.
+ */
+declare function analyzeGlare(input: string | Buffer | Uint8Array, options?: GlareOptions): Promise<GlareResult>;
+/**
+ * Returns only the normalized glare severity score (0.0 to 1.0).
+ *
+ * @param input - File path, Buffer, or Uint8Array.
+ * @param options - Optional glare options.
+ * @returns Promise resolving to a number between 0.0 and 1.0.
+ */
+declare function getGlareScore(input: string | Buffer | Uint8Array, options?: GlareOptions): Promise<number>;
+/**
+ * Determines whether an image has glare exceeding the given threshold.
+ *
+ * @param input - File path, Buffer, or Uint8Array.
+ * @param threshold - Glare score threshold (default: 0.15).
+ * @returns Promise resolving to a boolean.
+ */
+declare function isGlared(input: string | Buffer | Uint8Array, threshold?: number): Promise<boolean>;
+
+/**
+ * Validates the image input parameter.
+ */
+declare function validateInput(input: unknown): void;
+/**
+ * Validates and normalizes user-provided glare options with defaults.
+ */
+declare function normalizeOptions(options?: GlareOptions): Required<GlareOptions>;
+
+export { type GlareOptions, type GlareResult, analyzeGlare, getGlareScore, isGlared, normalizeOptions, validateInput };

package/dist/index.js

@@ -0,0 +1,261 @@
+import sharp from 'sharp';
+
+// src/detector.ts
+
+// src/utils.ts
+function validateInput(input) {
+  if (input === null || input === void 0) {
+    throw new TypeError("Invalid image input: input must be a file path string, Buffer, or Uint8Array.");
+  }
+  if (typeof input === "string") {
+    if (input.trim().length === 0) {
+      throw new Error("Invalid image input: file path string cannot be empty.");
+    }
+    return;
+  }
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+    if (input.length === 0) {
+      throw new Error("Invalid image input: buffer cannot be empty.");
+    }
+    return;
+  }
+  throw new TypeError("Invalid image input: expected a file path string, Buffer, or Uint8Array.");
+}
+function normalizeOptions(options) {
+  const threshold = options?.threshold ?? 0.15;
+  const luminanceCutoff = options?.luminanceCutoff ?? 245;
+  const minHotspotArea = options?.minHotspotArea ?? 50;
+  const downsampleWidth = options?.downsampleWidth ?? 512;
+  if (typeof threshold !== "number" || Number.isNaN(threshold) || threshold < 0 || threshold > 1) {
+    throw new RangeError(`Invalid option 'threshold': expected a number between 0 and 1, got ${threshold}.`);
+  }
+  if (typeof luminanceCutoff !== "number" || Number.isNaN(luminanceCutoff) || luminanceCutoff < 0 || luminanceCutoff > 255) {
+    throw new RangeError(
+      `Invalid option 'luminanceCutoff': expected a number between 0 and 255, got ${luminanceCutoff}.`
+    );
+  }
+  if (typeof minHotspotArea !== "number" || Number.isNaN(minHotspotArea) || minHotspotArea < 1 || !Number.isInteger(minHotspotArea)) {
+    throw new RangeError(
+      `Invalid option 'minHotspotArea': expected a positive integer >= 1, got ${minHotspotArea}.`
+    );
+  }
+  if (typeof downsampleWidth !== "number" || Number.isNaN(downsampleWidth) || downsampleWidth < 16 || !Number.isInteger(downsampleWidth)) {
+    throw new RangeError(
+      `Invalid option 'downsampleWidth': expected an integer >= 16, got ${downsampleWidth}.`
+    );
+  }
+  return {
+    threshold,
+    luminanceCutoff,
+    minHotspotArea,
+    downsampleWidth
+  };
+}
+
+// src/detector.ts
+async function analyzeGlare(input, options) {
+  validateInput(input);
+  const opts = normalizeOptions(options);
+  const imagePipeline = sharp(input);
+  const { data, info } = await imagePipeline.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.");
+  }
+  let peakLuminance = 0;
+  let luminanceSum = 0;
+  let saturatedPixelCount = 0;
+  for (let i = 0; i < totalPixels; i++) {
+    const lum = data[i];
+    if (lum > peakLuminance) peakLuminance = lum;
+    luminanceSum += lum;
+    if (lum >= opts.luminanceCutoff) {
+      saturatedPixelCount++;
+    }
+  }
+  const avgLuminance = Number((luminanceSum / totalPixels).toFixed(2));
+  if (saturatedPixelCount === 0) {
+    return {
+      score: 0,
+      hasGlare: false,
+      glarePercentage: 0,
+      hotspotCount: 0,
+      quality: "excellent",
+      details: {
+        peakLuminance,
+        avgLuminance,
+        saturatedPixelCount: 0
+      }
+    };
+  }
+  const visited = new Uint8Array(totalPixels);
+  const candidateClusters = [];
+  const queue = new Int32Array(totalPixels);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const startIdx = y * width + x;
+      if (visited[startIdx] === 1 || data[startIdx] < opts.luminanceCutoff) {
+        continue;
+      }
+      let head = 0;
+      let tail = 0;
+      queue[tail++] = startIdx;
+      visited[startIdx] = 1;
+      const clusterPixels = [];
+      let clusterLumSum = 0;
+      while (head < tail) {
+        const currIdx = queue[head++];
+        clusterPixels.push(currIdx);
+        clusterLumSum += data[currIdx];
+        const cx = currIdx % width;
+        const cy = Math.floor(currIdx / width);
+        if (cx + 1 < width) {
+          const nIdx = currIdx + 1;
+          if (visited[nIdx] === 0 && data[nIdx] >= opts.luminanceCutoff) {
+            visited[nIdx] = 1;
+            queue[tail++] = nIdx;
+          }
+        }
+        if (cx - 1 >= 0) {
+          const nIdx = currIdx - 1;
+          if (visited[nIdx] === 0 && data[nIdx] >= opts.luminanceCutoff) {
+            visited[nIdx] = 1;
+            queue[tail++] = nIdx;
+          }
+        }
+        if (cy + 1 < height) {
+          const nIdx = currIdx + width;
+          if (visited[nIdx] === 0 && data[nIdx] >= opts.luminanceCutoff) {
+            visited[nIdx] = 1;
+            queue[tail++] = nIdx;
+          }
+        }
+        if (cy - 1 >= 0) {
+          const nIdx = currIdx - width;
+          if (visited[nIdx] === 0 && data[nIdx] >= opts.luminanceCutoff) {
+            visited[nIdx] = 1;
+            queue[tail++] = nIdx;
+          }
+        }
+      }
+      if (clusterPixels.length < opts.minHotspotArea) {
+        continue;
+      }
+      if (clusterPixels.length / totalPixels > 0.75 && avgLuminance > 230) {
+        continue;
+      }
+      const meanClusterLum = clusterLumSum / clusterPixels.length;
+      const surroundingSet = /* @__PURE__ */ new Set();
+      const clusterSet = new Set(clusterPixels);
+      for (const pIdx of clusterPixels) {
+        const px = pIdx % width;
+        const py = Math.floor(pIdx / width);
+        for (let dy = -3; dy <= 3; dy++) {
+          const ny = py + dy;
+          if (ny < 0 || ny >= height) continue;
+          for (let dx = -3; dx <= 3; dx++) {
+            if (dx === 0 && dy === 0) continue;
+            if (Math.abs(dx) + Math.abs(dy) > 3) continue;
+            const nx = px + dx;
+            if (nx < 0 || nx >= width) continue;
+            const nIdx = ny * width + nx;
+            if (!clusterSet.has(nIdx)) {
+              surroundingSet.add(nIdx);
+            }
+          }
+        }
+      }
+      let surroundingLuminance = meanClusterLum;
+      let contrast = 0;
+      if (surroundingSet.size > 0) {
+        let surrSum = 0;
+        for (const sIdx of surroundingSet) {
+          surrSum += data[sIdx];
+        }
+        surroundingLuminance = surrSum / surroundingSet.size;
+        contrast = Math.max(0, meanClusterLum - surroundingLuminance);
+      }
+      if (contrast < 15) {
+        continue;
+      }
+      const contrastFactor = Math.min(1, Math.max(0.3, contrast / 50));
+      candidateClusters.push({
+        pixels: clusterPixels,
+        meanLuminance: meanClusterLum,
+        surroundingLuminance,
+        contrast,
+        contrastFactor
+      });
+    }
+  }
+  const hotspotCount = candidateClusters.length;
+  if (hotspotCount === 0) {
+    return {
+      score: 0,
+      hasGlare: false,
+      glarePercentage: 0,
+      hotspotCount: 0,
+      quality: "excellent",
+      details: {
+        peakLuminance,
+        avgLuminance,
+        saturatedPixelCount
+      }
+    };
+  }
+  let totalGlarePixels = 0;
+  let weightedContrastSum = 0;
+  for (const cluster of candidateClusters) {
+    totalGlarePixels += cluster.pixels.length;
+    weightedContrastSum += cluster.pixels.length * cluster.contrastFactor;
+  }
+  const glarePercentage = Number((totalGlarePixels / totalPixels * 100).toFixed(2));
+  const areaRatio = totalGlarePixels / totalPixels;
+  const avgContrastFactor = weightedContrastSum / totalGlarePixels;
+  const rawScore = Math.min(
+    1,
+    Math.sqrt(areaRatio) * 1.9 * (0.6 + 0.4 * avgContrastFactor)
+  );
+  const score = Number(rawScore.toFixed(4));
+  const hasGlare = score >= opts.threshold;
+  let quality;
+  if (score < 0.05) {
+    quality = "excellent";
+  } else if (score < opts.threshold) {
+    quality = "good";
+  } else if (score < 0.4) {
+    quality = "fair";
+  } else {
+    quality = "poor";
+  }
+  return {
+    score,
+    hasGlare,
+    glarePercentage,
+    hotspotCount,
+    quality,
+    details: {
+      peakLuminance,
+      avgLuminance,
+      saturatedPixelCount
+    }
+  };
+}
+async function getGlareScore(input, options) {
+  const result = await analyzeGlare(input, options);
+  return result.score;
+}
+async function isGlared(input, threshold) {
+  const options = {};
+  if (threshold !== void 0) {
+    options.threshold = threshold;
+  }
+  const result = await analyzeGlare(input, options);
+  return result.hasGlare;
+}
+
+export { analyzeGlare, getGlareScore, isGlared, normalizeOptions, validateInput };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/detector.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { GlareOptions } from './types';\n\n/**\n * Validates the image input parameter.\n */\nexport function validateInput(input: unknown): void {\n  if (input === null || input === undefined) {\n    throw new TypeError('Invalid image input: input must be a file path string, Buffer, or Uint8Array.');\n  }\n\n  if (typeof input === 'string') {\n    if (input.trim().length === 0) {\n      throw new Error('Invalid image input: file path string cannot be empty.');\n    }\n    return;\n  }\n\n  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {\n    if (input.length === 0) {\n      throw new Error('Invalid image input: buffer cannot be empty.');\n    }\n    return;\n  }\n\n  throw new TypeError('Invalid image input: expected a file path string, Buffer, or Uint8Array.');\n}\n\n/**\n * Validates and normalizes user-provided glare options with defaults.\n */\nexport function normalizeOptions(options?: GlareOptions): Required<GlareOptions> {\n  const threshold = options?.threshold ?? 0.15;\n  const luminanceCutoff = options?.luminanceCutoff ?? 245;\n  const minHotspotArea = options?.minHotspotArea ?? 50;\n  const downsampleWidth = options?.downsampleWidth ?? 512;\n\n  if (typeof threshold !== 'number' || Number.isNaN(threshold) || threshold < 0 || threshold > 1) {\n    throw new RangeError(`Invalid option 'threshold': expected a number between 0 and 1, got ${threshold}.`);\n  }\n\n  if (\n    typeof luminanceCutoff !== 'number' ||\n    Number.isNaN(luminanceCutoff) ||\n    luminanceCutoff < 0 ||\n    luminanceCutoff > 255\n  ) {\n    throw new RangeError(\n      `Invalid option 'luminanceCutoff': expected a number between 0 and 255, got ${luminanceCutoff}.`\n    );\n  }\n\n  if (\n    typeof minHotspotArea !== 'number' ||\n    Number.isNaN(minHotspotArea) ||\n    minHotspotArea < 1 ||\n    !Number.isInteger(minHotspotArea)\n  ) {\n    throw new RangeError(\n      `Invalid option 'minHotspotArea': expected a positive integer >= 1, got ${minHotspotArea}.`\n    );\n  }\n\n  if (\n    typeof downsampleWidth !== 'number' ||\n    Number.isNaN(downsampleWidth) ||\n    downsampleWidth < 16 ||\n    !Number.isInteger(downsampleWidth)\n  ) {\n    throw new RangeError(\n      `Invalid option 'downsampleWidth': expected an integer >= 16, got ${downsampleWidth}.`\n    );\n  }\n\n  return {\n    threshold,\n    luminanceCutoff,\n    minHotspotArea,\n    downsampleWidth,\n  };\n}\n","import sharp from 'sharp';\nimport type { GlareOptions, GlareResult } from './types';\nimport { normalizeOptions, validateInput } from './utils';\n\ninterface ClusterInfo {\n  pixels: number[];\n  meanLuminance: number;\n  surroundingLuminance: number;\n  contrast: number;\n  contrastFactor: number;\n}\n\n/**\n * Analyzes an image for specular glare and flash reflection hotspots.\n *\n * @param input - File path, Buffer, or Uint8Array representing an image.\n * @param options - Configurable parameters for glare detection.\n * @returns Promise resolving to a detailed GlareResult.\n */\nexport async function analyzeGlare(\n  input: string | Buffer | Uint8Array,\n  options?: GlareOptions\n): Promise<GlareResult> {\n  validateInput(input);\n  const opts = normalizeOptions(options);\n\n  // Resize maintaining aspect ratio to the downsample width for blazing performance\n  const imagePipeline = sharp(input);\n  const { data, info } = await imagePipeline\n    .resize({ width: opts.downsampleWidth, withoutEnlargement: true })\n    .grayscale()\n    .raw()\n    .toBuffer({ resolveWithObject: true });\n\n  const width = info.width;\n  const height = info.height;\n  const totalPixels = width * height;\n\n  if (totalPixels === 0) {\n    throw new Error('Image contains no pixel data.');\n  }\n\n  // 1. Calculate overall luminance stats & identify saturated pixels\n  let peakLuminance = 0;\n  let luminanceSum = 0;\n  let saturatedPixelCount = 0;\n\n  for (let i = 0; i < totalPixels; i++) {\n    const lum = data[i]!;\n    if (lum > peakLuminance) peakLuminance = lum;\n    luminanceSum += lum;\n    if (lum >= opts.luminanceCutoff) {\n      saturatedPixelCount++;\n    }\n  }\n\n  const avgLuminance = Number((luminanceSum / totalPixels).toFixed(2));\n\n  // If no pixels reach the luminance cutoff, image is pristine\n  if (saturatedPixelCount === 0) {\n    return {\n      score: 0,\n      hasGlare: false,\n      glarePercentage: 0,\n      hotspotCount: 0,\n      quality: 'excellent',\n      details: {\n        peakLuminance,\n        avgLuminance,\n        saturatedPixelCount: 0,\n      },\n    };\n  }\n\n  // 2. Connected Component Analysis on saturated pixels (4-way connectivity)\n  const visited = new Uint8Array(totalPixels);\n  const candidateClusters: ClusterInfo[] = [];\n\n  // Queue for BFS\n  const queue = new Int32Array(totalPixels);\n\n  for (let y = 0; y < height; y++) {\n    for (let x = 0; x < width; x++) {\n      const startIdx = y * width + x;\n\n      if (visited[startIdx] === 1 || data[startIdx]! < opts.luminanceCutoff) {\n        continue;\n      }\n\n      // Start BFS to extract connected saturated cluster\n      let head = 0;\n      let tail = 0;\n      queue[tail++] = startIdx;\n      visited[startIdx] = 1;\n\n      const clusterPixels: number[] = [];\n      let clusterLumSum = 0;\n\n      while (head < tail) {\n        const currIdx = queue[head++]!;\n        clusterPixels.push(currIdx);\n        clusterLumSum += data[currIdx]!;\n\n        const cx = currIdx % width;\n        const cy = Math.floor(currIdx / width);\n\n        // Check 4-connected neighbors\n        // Right\n        if (cx + 1 < width) {\n          const nIdx = currIdx + 1;\n          if (visited[nIdx] === 0 && data[nIdx]! >= opts.luminanceCutoff) {\n            visited[nIdx] = 1;\n            queue[tail++] = nIdx;\n          }\n        }\n        // Left\n        if (cx - 1 >= 0) {\n          const nIdx = currIdx - 1;\n          if (visited[nIdx] === 0 && data[nIdx]! >= opts.luminanceCutoff) {\n            visited[nIdx] = 1;\n            queue[tail++] = nIdx;\n          }\n        }\n        // Down\n        if (cy + 1 < height) {\n          const nIdx = currIdx + width;\n          if (visited[nIdx] === 0 && data[nIdx]! >= opts.luminanceCutoff) {\n            visited[nIdx] = 1;\n            queue[tail++] = nIdx;\n          }\n        }\n        // Up\n        if (cy - 1 >= 0) {\n          const nIdx = currIdx - width;\n          if (visited[nIdx] === 0 && data[nIdx]! >= opts.luminanceCutoff) {\n            visited[nIdx] = 1;\n            queue[tail++] = nIdx;\n          }\n        }\n      }\n\n      // Check if cluster meets minimum hotspot area threshold\n      if (clusterPixels.length < opts.minHotspotArea) {\n        continue;\n      }\n\n      // If cluster occupies virtually the whole image (> 75%) and avg luminance is very high,\n      // this is a diffuse white background or uniform paper, not a localized specular hotspot.\n      if (clusterPixels.length / totalPixels > 0.75 && avgLuminance > 230) {\n        continue;\n      }\n\n      const meanClusterLum = clusterLumSum / clusterPixels.length;\n\n      // 3. Local Contrast Analysis: Examine peripheral non-cluster pixels\n      // Collect immediate surrounding background pixels within a 3px dilation\n      const surroundingSet = new Set<number>();\n      const clusterSet = new Set<number>(clusterPixels);\n\n      for (const pIdx of clusterPixels) {\n        const px = pIdx % width;\n        const py = Math.floor(pIdx / width);\n\n        // Check surrounding window (up to 3 pixels away)\n        for (let dy = -3; dy <= 3; dy++) {\n          const ny = py + dy;\n          if (ny < 0 || ny >= height) continue;\n\n          for (let dx = -3; dx <= 3; dx++) {\n            if (dx === 0 && dy === 0) continue;\n            // Manhattan distance <= 3 for smooth circular neighborhood\n            if (Math.abs(dx) + Math.abs(dy) > 3) continue;\n\n            const nx = px + dx;\n            if (nx < 0 || nx >= width) continue;\n\n            const nIdx = ny * width + nx;\n            if (!clusterSet.has(nIdx)) {\n              surroundingSet.add(nIdx);\n            }\n          }\n        }\n      }\n\n      let surroundingLuminance = meanClusterLum;\n      let contrast = 0;\n\n      if (surroundingSet.size > 0) {\n        let surrSum = 0;\n        for (const sIdx of surroundingSet) {\n          surrSum += data[sIdx]!;\n        }\n        surroundingLuminance = surrSum / surroundingSet.size;\n        contrast = Math.max(0, meanClusterLum - surroundingLuminance);\n      }\n\n      // Specular glare has sharp local contrast (>= 15 luminance drop-off)\n      // Diffuse white paper has very low contrast (< 15)\n      if (contrast < 15) {\n        continue;\n      }\n\n      // Contrast factor scales between 0.3 (moderate contrast) to 1.0 (high contrast specular flash)\n      const contrastFactor = Math.min(1.0, Math.max(0.3, contrast / 50));\n\n      candidateClusters.push({\n        pixels: clusterPixels,\n        meanLuminance: meanClusterLum,\n        surroundingLuminance,\n        contrast,\n        contrastFactor,\n      });\n    }\n  }\n\n  // 4. Compute final GlareResult metrics\n  const hotspotCount = candidateClusters.length;\n\n  if (hotspotCount === 0) {\n    return {\n      score: 0,\n      hasGlare: false,\n      glarePercentage: 0,\n      hotspotCount: 0,\n      quality: 'excellent',\n      details: {\n        peakLuminance,\n        avgLuminance,\n        saturatedPixelCount,\n      },\n    };\n  }\n\n  let totalGlarePixels = 0;\n  let weightedContrastSum = 0;\n\n  for (const cluster of candidateClusters) {\n    totalGlarePixels += cluster.pixels.length;\n    weightedContrastSum += cluster.pixels.length * cluster.contrastFactor;\n  }\n\n  const glarePercentage = Number(((totalGlarePixels / totalPixels) * 100).toFixed(2));\n  const areaRatio = totalGlarePixels / totalPixels;\n  const avgContrastFactor = weightedContrastSum / totalGlarePixels;\n\n  // Normalized score calculation: concave sqrt curve mapping area + contrast\n  const rawScore = Math.min(\n    1.0,\n    Math.sqrt(areaRatio) * 1.9 * (0.6 + 0.4 * avgContrastFactor)\n  );\n  const score = Number(rawScore.toFixed(4));\n\n  const hasGlare = score >= opts.threshold;\n\n  let quality: 'excellent' | 'good' | 'fair' | 'poor';\n  if (score < 0.05) {\n    quality = 'excellent';\n  } else if (score < opts.threshold) {\n    quality = 'good';\n  } else if (score < 0.40) {\n    quality = 'fair';\n  } else {\n    quality = 'poor';\n  }\n\n  return {\n    score,\n    hasGlare,\n    glarePercentage,\n    hotspotCount,\n    quality,\n    details: {\n      peakLuminance,\n      avgLuminance,\n      saturatedPixelCount,\n    },\n  };\n}\n\n/**\n * Returns only the normalized glare severity score (0.0 to 1.0).\n *\n * @param input - File path, Buffer, or Uint8Array.\n * @param options - Optional glare options.\n * @returns Promise resolving to a number between 0.0 and 1.0.\n */\nexport async function getGlareScore(\n  input: string | Buffer | Uint8Array,\n  options?: GlareOptions\n): Promise<number> {\n  const result = await analyzeGlare(input, options);\n  return result.score;\n}\n\n/**\n * Determines whether an image has glare exceeding the given threshold.\n *\n * @param input - File path, Buffer, or Uint8Array.\n * @param threshold - Glare score threshold (default: 0.15).\n * @returns Promise resolving to a boolean.\n */\nexport async function isGlared(\n  input: string | Buffer | Uint8Array,\n  threshold?: number\n): Promise<boolean> {\n  const options: GlareOptions = {};\n  if (threshold !== undefined) {\n    options.threshold = threshold;\n  }\n  const result = await analyzeGlare(input, options);\n  return result.hasGlare;\n}\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "glare-score",
+  "version": "1.0.0",
+  "description": "Detect and quantify specular glare and flash reflection hotspots in images. Optimized for pre-OCR document scanning, KYC ID card verification, and photo quality pipelines.",
+  "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": [
+    "glare",
+    "glare-score",
+    "glare-detection",
+    "specular-reflection",
+    "flash-reflection",
+    "image-quality",
+    "kyc",
+    "ocr",
+    "document-scanning",
+    "id-verification",
+    "sharp",
+    "image-processing",
+    "hotspot-detection",
+    "photo-quality"
+  ],
+  "author": "Vijay Misal <misalvijay153@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vjymisal0/glare-score.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vjymisal0/glare-score/issues"
+  },
+  "homepage": "https://github.com/vjymisal0/glare-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"
+  }
+}