shadow-score 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay Misal <misalvijay153@gmail.com>
+
+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,333 @@
+# shadow-score 🌓
+
+[![npm version](https://img.shields.io/npm/v/shadow-score.svg?style=flat-square)](https://www.npmjs.com/package/shadow-score)
+[![license](https://img.shields.io/npm/l/shadow-score.svg?style=flat-square)](https://github.com/vjymisal0/shadow-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/shadow-score)
+[![Downloads](https://img.shields.io/npm/dm/shadow-score.svg?style=flat-square)](https://www.npmjs.com/package/shadow-score)
+
+> Detect and quantify **harsh directional shadows** cast across documents, paper, or identity cards (such as smartphone camera shadows during document capture) using **Otsu bimodal luminance segmentation** and **spatial illumination gradient analysis** with [`sharp`](https://sharp.pixelplumbing.com/).
+
+Companion package 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).
+
+---
+
+## 🌟 Why `shadow-score`?
+
+When users scan identity cards, receipts, or contracts with a smartphone, holding the phone directly over the document casts a harsh, dark shadow. Overhead room lights exacerbate this by creating high-contrast illumination gradients across the paper.
+
+These directional shadows severely impair downstream computer vision and OCR:
+- **Binarization failures**: Standard adaptive thresholding algorithms (Otsu, Bradley, Sauvola) create heavy dark blotches or wash out text along shadow boundaries.
+- **Silent OCR character dropouts**: Character recognition confidence plummets across shadowed regions in Tesseract, AWS Textract, and Google Cloud Vision.
+- **KYC rejection**: ID card verifiers fail automated document authenticity checks due to non-uniform illumination.
+
+`shadow-score` separates the low-frequency **illumination layer** from high-frequency text reflectance, runs **Otsu bimodal segmentation**, and evaluates the **spatial boundary gradient** to reliably measure shadow severity in milliseconds.
+
+### Key Highlights:
+- ⚡ **Sub-Millisecond Core Processing**: Optimized TypedArray operations and downsampling via native `sharp` C++ bindings.
+- 🎯 **Robust Illumination Separation**: Separable box filtering isolates macro illumination, preventing black text characters from being falsely classified as shadows.
+- 📐 **Bimodal & Spatial Analysis**: Evaluates Otsu between-class variance ($\sigma_B^2 / \sigma_T^2$), illumination delta, boundary gradient, and spatial cluster contiguity.
+- 📦 **Dual ESM & CommonJS**: Ships with complete ES Modules and CommonJS bundles plus strict TypeScript definitions.
+- 🛡️ **Zero Runtime Dependencies**: Depends strictly on standard `sharp`.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install shadow-score sharp
+```
+
+Or using your preferred package manager:
+
+```bash
+# pnpm
+pnpm add shadow-score sharp
+
+# yarn
+yarn add shadow-score sharp
+
+# bun
+bun add shadow-score sharp
+```
+
+> **Note**: `sharp` is required as a peer/direct dependency for high-performance image decoding and downsampling.
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```ts
+import { analyzeShadow, hasShadow, getShadowScore } from 'shadow-score';
+
+// 1. Boolean check (ideal for client retake prompts)
+const isShadowed = await hasShadow('./scanned-id.jpg');
+if (isShadowed) {
+  console.log('⚠️ Harsh shadow detected! Please adjust your lighting or angle.');
+}
+
+// 2. Normalized shadow score (0.0 = uniform lighting, 1.0 = heavy dark shadow)
+const score = await getShadowScore('./receipt.png');
+console.log(`Shadow Score: ${score}`); // e.g. 0.4215
+
+// 3. Full analysis with illumination metrics and quality rating
+const result = await analyzeShadow('./passport-page.jpg');
+console.log(result);
+/*
+{
+  score: 0.4821,
+  hasShadow: true,
+  shadowAreaPercentage: 38.45,
+  illuminationDelta: 118.60,
+  quality: 'poor',
+  details: {
+    litLuminance: 224.15,
+    shadowLuminance: 105.55,
+    otsuThreshold: 156,
+    separability: 0.7842,
+    boundaryGradient: 14.82
+  }
+}
+*/
+```
+
+---
+
+## 📖 API Reference
+
+### `analyzeShadow(input, options?): Promise<ShadowResult>`
+
+Performs comprehensive directional shadow analysis on an image.
+
+- **`input`**: File path string, `Buffer`, or `Uint8Array`.
+- **`options`**: Optional configuration object ([`ShadowOptions`](#shadowoptions)).
+- **Returns**: `Promise<ShadowResult>`
+
+#### `ShadowResult`
+
+```ts
+export interface ShadowResult {
+  /**
+   * Normalized shadow severity score from 0.0 (uniform lighting / shadow-free) to 1.0 (heavy dark shadow).
+   */
+  score: number;
+
+  /**
+   * Whether the image exceeds the shadow threshold (score >= threshold).
+   * @default threshold: 0.2
+   */
+  hasShadow: boolean;
+
+  /**
+   * Percentage of total image area under shadow (0.0 to 100.0).
+   */
+  shadowAreaPercentage: number;
+
+  /**
+   * Difference in average luminance between lit and shadowed regions (0.0 to 255.0).
+   */
+  illuminationDelta: number;
+
+  /**
+   * Qualitative lighting classification:
+   * - 'excellent': Uniform, pristine illumination (< 0.10).
+   * - 'good': Minor lighting variation or faint shadow, fully legible (< 0.20).
+   * - 'fair': Noticeable directional shadow, may degrade OCR accuracy (< 0.45).
+   * - 'poor': Severe, harsh shadow obscuring document content (>= 0.45).
+   */
+  quality: 'excellent' | 'good' | 'fair' | 'poor';
+
+  /**
+   * Low-level illumination and segmentation diagnostics.
+   */
+  details: ShadowDetails;
+}
+```
+
+#### `ShadowDetails`
+
+```ts
+export interface ShadowDetails {
+  /** Average luminance of the lit region (0.0 to 255.0). */
+  litLuminance: number;
+  /** Average luminance of the shadowed region (0.0 to 255.0). */
+  shadowLuminance: number;
+  /** Optimal Otsu threshold (0-255) computed across the illumination field. */
+  otsuThreshold: number;
+  /** Otsu bimodal separability ratio (eta = between-class variance / total variance, 0.0 to 1.0). */
+  separability: number;
+  /** Average directional spatial gradient magnitude along the shadow transition boundary. */
+  boundaryGradient: number;
+}
+```
+
+---
+
+### `getShadowScore(input, options?): Promise<number>`
+
+Convenience method that returns only the normalized shadow severity score (`0.0` to `1.0`).
+
+```ts
+const score = await getShadowScore(imageBuffer);
+```
+
+---
+
+### `hasShadow(input, thresholdOrOptions?): Promise<boolean>`
+
+Convenience method returning `true` if the detected shadow score meets or exceeds the threshold.
+
+```ts
+// Using default threshold (0.2)
+const flagged = await hasShadow('./document.jpg');
+
+// Custom numeric threshold
+const strict = await hasShadow('./document.jpg', 0.15);
+
+// Custom options object
+const custom = await hasShadow('./document.jpg', {
+  threshold: 0.25,
+  downsampleWidth: 384,
+});
+```
+
+---
+
+### `ShadowOptions`
+
+Configurable parameters to customize detection sensitivity:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `threshold` | `number` | `0.2` | Score cutoff for `hasShadow`. Image is flagged when `score >= threshold`. |
+| `downsampleWidth` | `number` | `256` | Target width downsampled before analysis. Ensures sub-millisecond execution. |
+| `minIlluminationDelta` | `number` | `20` | Minimum luminance drop (0-255) between lit and shadow zones to trigger detection. |
+| `smoothingRadius` | `number` | `4` | Radius of the separable 2D box filter to eliminate text characters and isolate illumination. |
+
+---
+
+## 🔬 How the Algorithm Works
+
+```
+Raw Input Image
+      │
+      ▼
+Downsample (e.g. 256px) & Grayscale Conversion
+      │
+      ▼
+Separable 2D Box Filter (Eliminates fine text & isolates illumination field L)
+      │
+      ▼
+Otsu Bimodal Thresholding (Maximizes between-class variance σ_B² / σ_T²)
+      │
+      ├───────────────────────────────┐
+      ▼                               ▼
+Illumination Delta & Area %      Boundary Spatial Gradient Analysis
+(Lit Mean vs. Shadow Mean)       (|∇L| step along shadow penumbra)
+      │                               │
+      └───────────────┬───────────────┘
+                      ▼
+        Spatial Cluster Contiguity
+        (Connected Component Analysis)
+                      │
+                      ▼
+      Normalized Shadow Score (0.0 to 1.0)
+```
+
+1. **Illumination Field Extraction**: High-resolution documents contain high-frequency reflectance details (ink letters, barcodes, signatures). A 2D separable box filter attenuates sharp, thin edges, leaving the macro ambient illumination field $L(x, y)$.
+2. **Otsu Bimodal Segmentation**: Evaluates histogram bimodality across $L(x, y)$ by finding threshold $t^*$ that maximizes between-class variance $\sigma_B^2(t)$. This segments candidate lit and candidate shadowed zones.
+3. **Boundary Spatial Gradient**: Directional shadows created by phones or hands feature a distinct penumbra boundary with a sharp illumination drop $|\nabla L|$. Diffuse room light gradients have near-zero boundary gradient and are scored low.
+4. **Spatial Cluster Contiguity**: Connected component analysis ensures that shadow pixels form a cohesive regional obstruction rather than scattered noise or image borders.
+5. **Calibrated Severity Score**: The combined factors produce a normalized, scale-invariant score from `0.0` (perfectly uniform) to `1.0` (harsh, dark shadow obscuring document).
+
+---
+
+## 💡 Practical Examples
+
+### Pre-OCR Document Quality Gate
+
+```ts
+import { analyzeShadow } from 'shadow-score';
+
+async function preprocessDocument(imagePath: string) {
+  const shadow = await analyzeShadow(imagePath);
+
+  if (shadow.score >= 0.45) {
+    throw new Error(
+      `Document rejected: heavy shadow detected (${shadow.shadowAreaPercentage}% of image affected). Please retake photo with even lighting.`
+    );
+  }
+
+  if (shadow.hasShadow) {
+    console.warn(
+      `Moderate shadow detected (score: ${shadow.score}). Applying local adaptive illumination correction before OCR...`
+    );
+  }
+
+  return shadow;
+}
+```
+
+### KYC ID Card Verification Pipeline
+
+Combine `shadow-score` with its companion libraries for comprehensive quality verification:
+
+```ts
+import { hasBlur } from 'blur-score';
+import { hasGlare } from 'glare-score';
+import { hasShadow } from 'shadow-score';
+
+async function validateIdCard(imageBuffer: Buffer) {
+  const [blurry, glared, shadowed] = await Promise.all([
+    hasBlur(imageBuffer),
+    hasGlare(imageBuffer),
+    hasShadow(imageBuffer),
+  ]);
+
+  if (blurry) return { valid: false, reason: 'Image is blurry. Please hold camera steady.' };
+  if (glared) return { valid: false, reason: 'Flash reflection detected. Please turn off camera flash.' };
+  if (shadowed) return { valid: false, reason: 'Phone shadow detected. Please avoid blocking overhead light.' };
+
+  return { valid: true };
+}
+```
+
+---
+
+## 🔗 Companion Packages
+
+Build an end-to-end automated image quality and document preprocessing pipeline:
+
+| Package | Purpose | Detection Method |
+| :--- | :--- | :--- |
+| [**`shadow-score`**](https://www.npmjs.com/package/shadow-score) | Harsh directional shadows & lighting gradients | Otsu bimodal segmentation & spatial gradient |
+| [**`glare-score`**](https://www.npmjs.com/package/glare-score) | Specular flash hotspots & reflection glare | Connected component labeling & boundary contrast |
+| [**`blur-score`**](https://www.npmjs.com/package/blur-score) | Defocus and motion blur detection | Modified Laplacian variance & frequency analysis |
+| [**`exposure-score`**](https://www.npmjs.com/package/exposure-score) | Underexposure and overexposure detection | Luminance histogram percentile distribution |
+| [**`contrast-score`**](https://www.npmjs.com/package/contrast-score) | Low contrast and washed-out text | RMS contrast & Michelson contrast metrics |
+
+---
+
+## 🛠️ Development & Testing
+
+```bash
+# Install dependencies
+npm install
+
+# Run test suite (15+ unit tests using synthetic test images)
+npm test
+
+# Build dual ESM/CJS bundles with TypeScript declarations
+npm run build
+
+# Run typecheck
+npm run typecheck
+```
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © [Vijay Misal](mailto:misalvijay153@gmail.com)

package/dist/index.cjs

@@ -0,0 +1,330 @@
+'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.2;
+  const downsampleWidth = options?.downsampleWidth ?? 256;
+  const minIlluminationDelta = options?.minIlluminationDelta ?? 20;
+  const smoothingRadius = options?.smoothingRadius ?? 4;
+  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 downsampleWidth !== "number" || Number.isNaN(downsampleWidth) || downsampleWidth < 16 || !Number.isInteger(downsampleWidth)) {
+    throw new RangeError(
+      `Invalid option 'downsampleWidth': expected an integer >= 16, got ${downsampleWidth}.`
+    );
+  }
+  if (typeof minIlluminationDelta !== "number" || Number.isNaN(minIlluminationDelta) || minIlluminationDelta < 0 || minIlluminationDelta > 255) {
+    throw new RangeError(
+      `Invalid option 'minIlluminationDelta': expected a number between 0 and 255, got ${minIlluminationDelta}.`
+    );
+  }
+  if (typeof smoothingRadius !== "number" || Number.isNaN(smoothingRadius) || smoothingRadius < 1 || smoothingRadius > 32 || !Number.isInteger(smoothingRadius)) {
+    throw new RangeError(
+      `Invalid option 'smoothingRadius': expected an integer between 1 and 32, got ${smoothingRadius}.`
+    );
+  }
+  return {
+    threshold,
+    downsampleWidth,
+    minIlluminationDelta,
+    smoothingRadius
+  };
+}
+
+// src/detector.ts
+function extractIlluminationMap(src, width, height, radius) {
+  const temp = new Uint8Array(width * height);
+  const dst = new Uint8Array(width * height);
+  const div = 2 * radius + 1;
+  for (let y = 0; y < height; y++) {
+    const row = y * width;
+    let sum = 0;
+    for (let i = -radius; i <= radius; i++) {
+      const c = i < 0 ? 0 : i >= width ? width - 1 : i;
+      sum += src[row + c];
+    }
+    for (let x = 0; x < width; x++) {
+      temp[row + x] = Math.round(sum / div);
+      const removeX = x - radius;
+      const addX = x + radius + 1;
+      const removeVal = src[row + (removeX < 0 ? 0 : removeX)];
+      const addVal = src[row + (addX >= width ? width - 1 : addX)];
+      sum += addVal - removeVal;
+    }
+  }
+  for (let x = 0; x < width; x++) {
+    let sum = 0;
+    for (let i = -radius; i <= radius; i++) {
+      const r = i < 0 ? 0 : i >= height ? height - 1 : i;
+      sum += temp[r * width + x];
+    }
+    for (let y = 0; y < height; y++) {
+      dst[y * width + x] = Math.round(sum / div);
+      const removeY = y - radius;
+      const addY = y + radius + 1;
+      const removeVal = temp[(removeY < 0 ? 0 : removeY) * width + x];
+      const addVal = temp[(addY >= height ? height - 1 : addY) * width + x];
+      sum += addVal - removeVal;
+    }
+  }
+  return dst;
+}
+function computeContiguity(isShadow, width, height, totalShadowPixels) {
+  if (totalShadowPixels === 0) return 0;
+  const totalPixels = width * height;
+  const visited = new Uint8Array(totalPixels);
+  const queue = new Int32Array(totalPixels);
+  let maxClusterSize = 0;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const startIdx = y * width + x;
+      if (visited[startIdx] === 1 || isShadow[startIdx] === 0) continue;
+      let head = 0;
+      let tail = 0;
+      queue[tail++] = startIdx;
+      visited[startIdx] = 1;
+      let clusterSize = 0;
+      while (head < tail) {
+        const curr = queue[head++];
+        clusterSize++;
+        const cy = Math.floor(curr / width);
+        const cx = curr % width;
+        if (cx > 0) {
+          const n = curr - 1;
+          if (visited[n] === 0 && isShadow[n] === 1) {
+            visited[n] = 1;
+            queue[tail++] = n;
+          }
+        }
+        if (cx < width - 1) {
+          const n = curr + 1;
+          if (visited[n] === 0 && isShadow[n] === 1) {
+            visited[n] = 1;
+            queue[tail++] = n;
+          }
+        }
+        if (cy > 0) {
+          const n = curr - width;
+          if (visited[n] === 0 && isShadow[n] === 1) {
+            visited[n] = 1;
+            queue[tail++] = n;
+          }
+        }
+        if (cy < height - 1) {
+          const n = curr + width;
+          if (visited[n] === 0 && isShadow[n] === 1) {
+            visited[n] = 1;
+            queue[tail++] = n;
+          }
+        }
+      }
+      if (clusterSize > maxClusterSize) {
+        maxClusterSize = clusterSize;
+      }
+    }
+  }
+  return maxClusterSize / totalShadowPixels;
+}
+async function analyzeShadow(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.");
+  }
+  const illum = extractIlluminationMap(data, width, height, opts.smoothingRadius);
+  const hist = new Int32Array(256);
+  let totalSum = 0;
+  for (let i = 0; i < totalPixels; i++) {
+    const val = illum[i];
+    hist[val]++;
+    totalSum += val;
+  }
+  const meanT = totalSum / totalPixels;
+  let varT = 0;
+  for (let i = 0; i < 256; i++) {
+    const count = hist[i];
+    if (count > 0) {
+      const diff = i - meanT;
+      varT += count * diff * diff;
+    }
+  }
+  varT /= totalPixels;
+  if (varT < 1) {
+    const roundedMean = Number(meanT.toFixed(2));
+    return {
+      score: 0,
+      hasShadow: false,
+      shadowAreaPercentage: 0,
+      illuminationDelta: 0,
+      quality: "excellent",
+      details: {
+        litLuminance: roundedMean,
+        shadowLuminance: roundedMean,
+        otsuThreshold: Math.round(meanT),
+        separability: 0,
+        boundaryGradient: 0
+      }
+    };
+  }
+  let bestT = 128;
+  let maxBetweenVar = 0;
+  let weight0 = 0;
+  let sum0 = 0;
+  for (let t = 0; t < 255; t++) {
+    const count = hist[t];
+    weight0 += count;
+    if (weight0 === 0) continue;
+    const weight1 = totalPixels - weight0;
+    if (weight1 === 0) break;
+    sum0 += t * count;
+    const mean0 = sum0 / weight0;
+    const mean1 = (totalSum - sum0) / weight1;
+    const meanDiff = mean1 - mean0;
+    const betweenVar = weight0 * weight1 * meanDiff * meanDiff / (totalPixels * totalPixels);
+    if (betweenVar > maxBetweenVar) {
+      maxBetweenVar = betweenVar;
+      bestT = t;
+    }
+  }
+  let shadowCount = 0;
+  let shadowSum = 0;
+  let litCount = 0;
+  let litSum = 0;
+  const isShadow = new Uint8Array(totalPixels);
+  for (let i = 0; i < totalPixels; i++) {
+    const val = illum[i];
+    if (val <= bestT) {
+      isShadow[i] = 1;
+      shadowCount++;
+      shadowSum += val;
+    } else {
+      litCount++;
+      litSum += val;
+    }
+  }
+  const shadowLuminance = shadowCount > 0 ? shadowSum / shadowCount : 0;
+  const litLuminance = litCount > 0 ? litSum / litCount : meanT;
+  const illuminationDelta = Math.max(0, litLuminance - shadowLuminance);
+  const shadowAreaPercentage = shadowCount / totalPixels * 100;
+  const separability = Math.min(1, maxBetweenVar / varT);
+  let boundaryGradientSum = 0;
+  let boundaryPixelCount = 0;
+  for (let y = 1; y < height - 1; y++) {
+    const rowOffset = y * width;
+    for (let x = 1; x < width - 1; x++) {
+      const idx = rowOffset + x;
+      if (isShadow[idx] === 1) {
+        if (isShadow[idx - 1] === 0 || isShadow[idx + 1] === 0 || isShadow[idx - width] === 0 || isShadow[idx + width] === 0) {
+          const gx = (illum[idx + 1] - illum[idx - 1]) * 0.5;
+          const gy = (illum[idx + width] - illum[idx - width]) * 0.5;
+          boundaryGradientSum += Math.sqrt(gx * gx + gy * gy);
+          boundaryPixelCount++;
+        }
+      }
+    }
+  }
+  const avgBoundaryGradient = boundaryPixelCount > 0 ? boundaryGradientSum / boundaryPixelCount : 0;
+  const contiguity = computeContiguity(isShadow, width, height, shadowCount);
+  let score = 0;
+  if (illuminationDelta >= opts.minIlluminationDelta && shadowAreaPercentage > 0) {
+    const deltaRange = Math.max(1, 120 - opts.minIlluminationDelta);
+    const fDelta = Math.min(1, (illuminationDelta - opts.minIlluminationDelta) / deltaRange);
+    const fSep = Math.min(1, Math.max(0, (separability - 0.25) / 0.55));
+    const contrastRatio = illuminationDelta / (litLuminance + shadowLuminance + 1e-5);
+    const fContrast = Math.min(1, contrastRatio / 0.45);
+    const fGrad = Math.min(1, avgBoundaryGradient / 8);
+    const gradientTerm = 0.65 + 0.35 * fGrad;
+    let fArea = 1;
+    if (shadowAreaPercentage < 5) {
+      fArea = Math.max(0, shadowAreaPercentage / 5);
+    } else if (shadowAreaPercentage > 75) {
+      fArea = Math.max(0, (95 - shadowAreaPercentage) / 20);
+    }
+    const fLit = Math.min(1, litLuminance / 60);
+    const fContig = 0.4 + 0.6 * Math.min(1, Math.max(0, (contiguity - 0.2) / 0.5));
+    const contrastTerm = 0.5 * fSep + 0.5 * fContrast;
+    const rawScore = fDelta * contrastTerm * gradientTerm * fArea * fLit * fContig;
+    score = Math.max(0, Math.min(1, rawScore));
+  }
+  score = Number(score.toFixed(4));
+  const hasShadowResult = score >= opts.threshold;
+  let quality;
+  if (score < 0.1) {
+    quality = "excellent";
+  } else if (score < 0.2) {
+    quality = "good";
+  } else if (score < 0.45) {
+    quality = "fair";
+  } else {
+    quality = "poor";
+  }
+  const details = {
+    litLuminance: Number(litLuminance.toFixed(2)),
+    shadowLuminance: Number(shadowLuminance.toFixed(2)),
+    otsuThreshold: bestT,
+    separability: Number(separability.toFixed(4)),
+    boundaryGradient: Number(avgBoundaryGradient.toFixed(2))
+  };
+  return {
+    score,
+    hasShadow: hasShadowResult,
+    shadowAreaPercentage: Number(shadowAreaPercentage.toFixed(2)),
+    illuminationDelta: Number(illuminationDelta.toFixed(2)),
+    quality,
+    details
+  };
+}
+async function getShadowScore(input, options) {
+  const result = await analyzeShadow(input, options);
+  return result.score;
+}
+async function hasShadow(input, thresholdOrOptions) {
+  let opts;
+  if (typeof thresholdOrOptions === "number") {
+    opts = { threshold: thresholdOrOptions };
+  } else if (thresholdOrOptions !== void 0) {
+    opts = thresholdOrOptions;
+  }
+  const result = await analyzeShadow(input, opts);
+  return result.hasShadow;
+}
+
+exports.analyzeShadow = analyzeShadow;
+exports.getShadowScore = getShadowScore;
+exports.hasShadow = hasShadow;
+exports.normalizeOptions = normalizeOptions;
+exports.validateInput = validateInput;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map