blur-score 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# blur-score
+
+Detect how blurry an image is. Returns a sharpness score from `0` (very blurry) to `1` (very sharp) using the [variance of Laplacian](https://en.wikipedia.org/wiki/Discrete_Laplace_operator) method.
+
+## Install
+
+```bash
+npm install blur-score
+```
+
+Requires Node.js >= 18. Uses [`sharp`](https://sharp.pixelplumbing.com/) internally for image decoding.
+
+## Usage
+
+```js
+import { getBlurScore, isBlurry } from 'blur-score';
+
+// From a file path
+const score = await getBlurScore('photo.jpg'); // e.g. 0.83
+
+// From a Buffer
+const score2 = await getBlurScore(fs.readFileSync('photo.jpg'));
+
+// From a URL
+const score3 = await getBlurScore('https://example.com/photo.jpg');
+
+// Check against a threshold - true if score is below the threshold
+const blurry = await isBlurry('photo.jpg', 0.5);
+```
+
+CommonJS is also supported via dynamic import:
+
+```js
+const { getBlurScore, isBlurry } = await import('blur-score');
+```
+
+## API
+
+### `getBlurScore(input, options?)`
+
+Returns `Promise<number>` - a sharpness score between 0 and 1.
+
+- `input`: a file path (`string`), an `http(s)` URL (`string`), or image bytes (`Buffer` / `Uint8Array`).
+- `options.calibration` (default `60`): the Laplacian variance value that maps to a score of `0.5`. Raise it if sharp images score too high for your dataset; lower it if blurry images score too high.
+
+### `isBlurry(input, threshold?, options?)`
+
+Returns `Promise<boolean>` - `true` when the image's sharpness score is **below** `threshold`.
+
+- `threshold` (default `0.5`): the cutoff sharpness score.
+- `options`: same as `getBlurScore`.
+
+## How it works
+
+1. The image is converted to greyscale.
+2. A Laplacian kernel is convolved over the pixels to highlight edges.
+3. The variance of the Laplacian response is computed - sharp images with lots of edges produce high variance, blurry images produce low variance.
+4. The variance is mapped to a `0-1` score via `variance / (variance + calibration)`.
+
+Because the raw variance is unbounded and depends heavily on image content (not just blur), the `calibration` constant may need tuning for your specific use case.
+
+## Calibration notes
+
+Real Laplacian variance is much lower than you might expect: a genuinely sharp handheld photo typically lands in the 20-100 range, while a UI screenshot with crisp text can hit 10,000+. The default `calibration: 60` is tuned against real photos (not screenshots) so that:
+
+- Sharp, in-focus photos score roughly 0.5-0.7
+- Mild, barely-visible blur drops that to ~0.2-0.3
+- Clearly blurred images drop below 0.1
+
+**Known limitation:** this method measures edge/high-frequency content, not "blur" directly. A photo with genuinely low detail - a soft-focus shot, a shallow depth-of-field background, a smooth studio backdrop - can score similarly low even when perfectly sharp, because there just isn't much high-frequency content to measure. If your images are visually distinctive in this way (product shots on plain backgrounds, portraits, macro photography), test against a representative sample and adjust `calibration` or your threshold accordingly rather than trusting the default blindly.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "blur-score",
+  "version": "1.0.0",
+  "description": "Detect how blurry an image is (0-1 sharpness score) using Laplacian variance",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "keywords": [
+    "blur",
+    "blur-detection",
+    "image-processing",
+    "sharpness",
+    "laplacian",
+    "sharp"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "sharp": "^0.35.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,27 @@
+export interface BlurScoreOptions {
+  /**
+   * Laplacian variance value that maps to a sharpness score of 0.5.
+   * Raise it if sharp images are being scored too high; lower it if
+   * blurry images are being scored too high. Default: 60.
+   */
+  calibration?: number;
+}
+
+/**
+ * Computes a sharpness score for an image in the range [0, 1].
+ * 1 means very sharp, 0 means very blurry.
+ */
+export function getBlurScore(
+  input: string | Buffer | Uint8Array,
+  options?: BlurScoreOptions
+): Promise<number>;
+
+/**
+ * Determines whether an image is blurry relative to a sharpness threshold.
+ * An image is considered blurry when its sharpness score is below `threshold`.
+ */
+export function isBlurry(
+  input: string | Buffer | Uint8Array,
+  threshold?: number,
+  options?: BlurScoreOptions
+): Promise<boolean>;

package/src/index.js

@@ -0,0 +1,28 @@
+import { loadImageBuffer } from './loadImage.js';
+import { computeLaplacianVariance, varianceToScore } from './laplacian.js';
+
+/**
+ * Computes a sharpness score for an image in the range [0, 1].
+ * 1 means very sharp, 0 means very blurry.
+ * @param {string | Buffer | Uint8Array} input - File path, http(s) URL, or image bytes.
+ * @param {{ calibration?: number }} [options]
+ * @returns {Promise<number>}
+ */
+export async function getBlurScore(input, options = {}) {
+  const buffer = await loadImageBuffer(input);
+  const variance = await computeLaplacianVariance(buffer);
+  return varianceToScore(variance, options.calibration);
+}
+
+/**
+ * Determines whether an image is blurry relative to a sharpness threshold.
+ * An image is considered blurry when its sharpness score is below `threshold`.
+ * @param {string | Buffer | Uint8Array} input - File path, http(s) URL, or image bytes.
+ * @param {number} [threshold=0.5] - Sharpness score below which an image counts as blurry (0-1).
+ * @param {{ calibration?: number }} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function isBlurry(input, threshold = 0.5, options = {}) {
+  const score = await getBlurScore(input, options);
+  return score < threshold;
+}

package/src/laplacian.js

@@ -0,0 +1,63 @@
+import sharp from 'sharp';
+
+// Standard 4-neighbor discrete Laplacian kernel used for edge/focus detection.
+const KERNEL_OFFSETS = [
+  [0, -1, 1],
+  [-1, 0, 1],
+  [0, 0, -4],
+  [1, 0, 1],
+  [0, 1, 1],
+];
+
+/**
+ * Computes the variance of the Laplacian of an image buffer.
+ * Sharp, high-detail images produce large edge responses and high variance;
+ * blurry images produce weak, uniform responses and low variance.
+ * @param {Buffer} imageBuffer
+ * @returns {Promise<number>}
+ */
+export async function computeLaplacianVariance(imageBuffer) {
+  const { data, info } = await sharp(imageBuffer)
+    .greyscale()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  const { width, height } = info;
+
+  if (width < 3 || height < 3) {
+    throw new Error('Image must be at least 3x3 pixels to compute a Laplacian');
+  }
+
+  let sum = 0;
+  let sumSquares = 0;
+  let count = 0;
+
+  for (let y = 1; y < height - 1; y++) {
+    for (let x = 1; x < width - 1; x++) {
+      let response = 0;
+      for (const [dx, dy, weight] of KERNEL_OFFSETS) {
+        response += weight * data[(y + dy) * width + (x + dx)];
+      }
+      sum += response;
+      sumSquares += response * response;
+      count++;
+    }
+  }
+
+  const mean = sum / count;
+  return sumSquares / count - mean * mean;
+}
+
+/**
+ * Maps an unbounded Laplacian variance to a 0-1 sharpness score.
+ * Higher variance (sharper, more edges) approaches 1; low variance (blurry) approaches 0.
+ * `calibration` is the variance value that maps to a score of 0.5 - tune it against
+ * representative images if the defaults misclassify your dataset.
+ * @param {number} variance
+ * @param {number} calibration
+ * @returns {number}
+ */
+export function varianceToScore(variance, calibration = 60) {
+  const score = variance / (variance + calibration);
+  return Math.min(1, Math.max(0, score));
+}

package/src/loadImage.js

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+
+const URL_PATTERN = /^https?:\/\//i;
+
+/**
+ * Resolves a path, URL, or Buffer/Uint8Array input into an image Buffer.
+ * @param {string | Buffer | Uint8Array} input
+ * @returns {Promise<Buffer>}
+ */
+export async function loadImageBuffer(input) {
+  if (Buffer.isBuffer(input)) {
+    return input;
+  }
+
+  if (input instanceof Uint8Array) {
+    return Buffer.from(input);
+  }
+
+  if (typeof input === 'string') {
+    if (URL_PATTERN.test(input)) {
+      const response = await fetch(input);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch image from URL: ${response.status} ${response.statusText}`);
+      }
+      return Buffer.from(await response.arrayBuffer());
+    }
+    return readFile(input);
+  }
+
+  throw new TypeError('Image input must be a file path, an http(s) URL, or a Buffer/Uint8Array');
+}