image_quality_gate #

Reject bad photos before OCR, upload or document scanning, and tell the user exactly why. Pure Dart, web-safe, one dependency (package:image).

Features #

• ImageQualityGate(config).evaluate(bytes) returns a QualityReport with passed, a list of typed QualityIssues and all the raw QualityMetrics. Each issue carries its code, the metric it came from, the measured value, the threshold, whether that threshold is a minimum or a maximum, and a severity (error rejects, warning only informs).
• evaluateImage(Image) for images you have already decoded.
• Checks:
  • Sharpness: variance of the Laplacian, with Tenengrad (Sobel gradient energy) as an optional second metric.
  • Exposure: mean luminance too dark or too bright, plus the fractions of clipped highlights and shadows.
  • Glare: the fraction of saturated near-white pixels, optionally only those in connected blobs so scattered specks are ignored.
  • Low contrast: RMS contrast.
  • Resolution: minimum width, height and megapixels, and an aspect-ratio range.
  • Document fill (a heuristic): flags a document that is too small in the frame.
• Presets: QualityConfig.receipt, idCard, document and photo.
• Region of interest: full frame, centre crop, relative rectangle or pixel rectangle.
• evaluateInIsolate (from image_quality_gate_io.dart) runs the work on a background isolate with Isolate.run. The main library imports neither dart:io nor dart:isolate, so it also works on the web.
• Built-in messages in English, French and Arabic for every issue code. You can override any of them.

Install #

dart pub add image_quality_gate

Usage #

import 'dart:typed_data';

import 'package:image_quality_gate/image_quality_gate.dart';

void check(Uint8List bytes) {
  const gate = ImageQualityGate(QualityConfig.receipt);
  final report = gate.evaluate(bytes);

  if (!report.passed) {
    final messages = QualityMessages.forLocale('fr');
    for (final issue in report.errors) {
      print(messages.forIssue(issue));
      // e.g. "Photo floue. Tenez le téléphone immobile et recommencez."
      print('${issue.metric} = ${issue.value} (${issue.kind.name} ${issue.threshold})');
    }
  }
  print(report.metrics.laplacianVariance);
}

On a background isolate (native platforms only):

import 'package:image_quality_gate/image_quality_gate_io.dart';

Future<bool> isUsable(Uint8List bytes) async =>
    (await evaluateInIsolate(bytes, QualityConfig.document)).passed;

Custom thresholds, a region of interest, and your own wording:

final config = QualityConfig.idCard.copyWith(
  roi: const RegionOfInterest.centre(widthFraction: 0.9, heightFraction: 0.7),
  glare: const GlareCheck(maxFraction: 0.002),
  disable: {QualityCheck.documentFill},
);
final messages = QualityMessages.forLocale('ar', overrides: {
  QualityIssueCode.glare: 'أمِل البطاقة قليلًا لإزالة الانعكاس.',
});

A decode failure throws UndecodableImageException. evaluate applies EXIF orientation first, so width, height and the region of interest match what the user saw on screen.

How it measures #

Luminance is Rec. 601 luma (0.299 R + 0.587 G + 0.114 B) on a 0..255 scale, whatever the bit depth of the source.

Sharpness sample. Downscaling is a low-pass filter. A mild blur on a 12 MP photo shrinks to a fraction of a pixel on a 500 px copy and the blur signal disappears; one test in this package shows this. By default the Laplacian is therefore measured on a 600 x 600 window at native resolution, taken from the centre of the region of interest. To measure the whole region downscaled to workingSize instead, set SharpnessCheck(window: null, workingSize: ...). Both metrics depend on scale and content. A threshold tuned for one camera resolution does not carry over to another.

Working image. A single pass reads every pixel in the region. It gathers the exposure, contrast and glare statistics, and it builds an area-averaged copy whose long side is QualityConfig.workingSize (512 by default). Glare blobs and the document-fill heuristic run on that copy.

Document fill is a heuristic. Strong edges (Sobel magnitude ≥ edgeThreshold) are found on the working image. documentFill is the area of the box holding the central 96% of edge pixels on each axis, divided by the region's area. It works for a document with visible content or a visible border on a plainer background. A busy background (wood grain, a patterned cloth) inflates it, and a blank page deflates it. It is not document detection, so its presets report it as a warning, not an error.

How the presets were chosen #

No published standard gives thresholds for these metrics on phone photos. Each value below is either taken from a source or is an engineering choice. Treat all of them as starting points and tune them on your own photos.

The synthetic tests check that the presets order images correctly (sharp before blurred, dark before bright). They do not check that the thresholds are right for real photos. No real-photo corpus was used.

Performance #

Measured with benchmark/benchmark.dart on a generated 4000 x 3000 (12 MP) JPEG (quality 90, 3.6 MB), compiled with dart compile exe, on an Intel Core i7-6700HQ (2016 laptop, 4 cores). The machine was busy with other jobs during the run (load average 13-16), so these numbers are upper bounds.

Decoding dominates. evaluateImage reads each pixel of the region once; everything else runs on a 512 px copy or a 600 px window. In practice:

• Cap the capture size (for example, image_picker's maxWidth: 2400). A photo of a receipt or a page gains nothing from 48 MP.
• Use evaluateInIsolate so the UI isolate never waits for the decode.
• If a platform codec gives you decoded pixels faster, build an Image and call evaluateImage. Keep in mind that decoding at reduced size lowers the sharpness metrics, so thresholds need re-tuning.

Limitations #

• Thresholds are content- and scale-dependent. A page with little text has a lower Laplacian variance than a busy one at the same focus.
• Only the centre window is checked for sharpness by default, so a photo that is sharp in the centre and blurred at the edges (tilted document, shallow depth of field) passes. Use a region of interest or window: null if that matters.
• Glare detection finds saturated near-white areas. It cannot tell a reflection from a genuinely white object that is overexposed.
• Document fill is a heuristic (see above), not document detection or perspective estimation.
• Aspect ratio is long side over short side, so it ignores orientation. minWidth and minHeight are literal, so the presets set both to the same value.
• evaluate depends on package:image's decoders, which are pure Dart and slow on large JPEGs.

License #

MIT. See LICENSE.

Made by Abdeldjalil Chougui.